REST API

Introduction

This is the reference document for the REST API of Clepsydra Storage.

The API calls return by default content of the type application/xml. Parameters passed in query strings are either integers, dates or arbitrary character strings. All dates are of the format yyyy-MM-dd'T'HH:mm:ss'Z', e.g. 2012-10-24T16:40:16Z.

Data Structures

Header

ParamTypeDescription
idLongrecord identifier
fbcIdStringflexible backward compatible identifier
objectIdStringobject identifier
schemaIdStringschema identifier
sourceIdStringsource identifier
processingPathStringprocessing path
sourceObjectLastModificationDateDatesource object last modification date
lastUpdateDateDatelast update date
deleteDateDatedelete date
lastProcessingDateDatelast processing date
checksumStringchecksum
appearanceDateDateappearance date

Resource /records

GET /records

Description

Searches for records using specified parameters. Returns an XML document with the root element <recordQueryResult>. Records are enclosed in the <records> tags within <recordQueryResult> and every single record is enclosed in the <record> tags within <records>. The content of a record is stored in the <data> subelement of <record> encoded as a base64 string.

The results are paged. The default limit is set to 200 records per page. One may change the limit by setting the pl.psnc.synat.a9.ms.rest.recordsListSize property of the Jersey Web Application servlet in the web.xml file. Every page is an XML document. If the number of records exceeds the limit, the document contains the element <nextPageToken> within <recordQueryResult>. The content of the <nextPageToken> may be passed as a value of the token parameter in the following request in order to obtain the next page.

Parameters

ParamTypeRequiredDescription
sourceFromDateNosource object last modification date has to be greater than this value
sourceUntilDateNosource object last modification date has to be lower than this value
fromDateNolast modification date has to be greater than this value
untilDateNolast modification date has to be lower than this value
isProcessedBooleanNorecord has to be processed
schemaIdStringNoschema identifier has to be equal to this value
sourceIdStringNosource identifier has to be equal to this value
objectIdStringNoobject identifier has to be equal to this value
isDeletedBooleanNorecord has to be marked as deleted
tokenStringNoretrieves results for the specified token
thresholdIdIntegerNorecord identifier has to be greater than this value
fbcIdStringNofbc identifier
appearanceFromDateNoappearance date has to be lower than this value
appearanceUntilDateNoappearance date has to be greater than this value

Status Codes

CodeDescription
200The records have been successfully retrieved.
404The page for the given token is not found.
500An internal server error has occurred.

Sample Call

curl -X GET 'http://localhost:8080/clepsydra-storage/rest/records?from=2012-10-24T16:40:16Z&until=2012-11-08T15:45:38Z'

Sample Response

<recordQueryResult>
    <expirationDate>2013-02-07T17:05:42.327+01:00</expirationDate>
    <nextPageToken>06b135cf-9c89-4e3a-9b7a-90f5459f12b3</nextPageToken>
    <token>97f7ea79-217d-416c-856f-4fe800752364</token>
    <records>
        <record>
            <data>
                TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW5nIGVsaXQu
            </data>
            <header>
                <appearanceDate>2012-11-08T14:45:31.765+01:00</appearanceDate>
                <checksum>1491cd1220436c290261fc55f52362f9</checksum>
                <fbcId>nnnnnnh</fbcId>
                <id>1</id>
                <lastUpdateDate>2012-11-08T14:45:31.719+01:00</lastUpdateDate>
                <objectId>oai:localhost:81</objectId>
                <processingPath/>
                <schemaId>oai_dc</schemaId>
                <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
                <sourceObjectLastModificationDate>2012-10-12T11:37:22+02:00</sourceObjectLastModificationDate>
            </header>
        </record>
        <record>
            <data>
                IFByb2luIG5pYmggYXVndWUsIHN1c2NpcGl0IGEsIHNjZWxlcmlzcXVlIHNlZCwgbGFjaW5pYSBp
            </data>
            <header>
                <appearanceDate>2012-11-08T14:45:38.801+01:00</appearanceDate>
                <checksum>bde2c19dd67d3119f3d66603c0b6a716</checksum>
                <fbcId>nnnnng3</fbcId>
                <id>200</id>
                <lastUpdateDate>2012-11-08T14:45:38.801+01:00</lastUpdateDate>
                <objectId>oai:localhost:70</objectId>
                <processingPath/>
                <schemaId>setSpecs</schemaId>
                <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
                <sourceObjectLastModificationDate>2012-10-11T13:17:30+02:00</sourceObjectLastModificationDate>
            </header>
        </record>
    </records>
</recordQueryResult>

GET /records/{id}

Description

Retrieves the record with the identifier {id}.

If the "multipart/mixed" content is requested the response consists of two parts:

  • an "application/xml" part that contains the header
  • an "application/octet-stream" part that contains the record data.

Otherwise, the record is as an XML file with data stored in the <data> subelement encoded as a base64 string.

Path elements

Path elementTypeDescription
idIntegerrecord identifier

Status Codes

CodeDescription
200The record has been successfully retrieved.
404The record with the given {id} does not exist.
500An internal server error has occurred.

Sample Call

curl -X GET http://localhost:8080/clepsydra-storage/rest/records/81

Sample Response

<record>
    <data>
        TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW5nIGVsaXQu
    </data>
    <header>
        <appearanceDate>2012-11-08T14:45:36.264+01:00</appearanceDate>
        <checksum>03385cc68f3f0fadf7a4edf55076bf75</checksum>
        <fbcId>nnnnnhV</fbcId>
        <id>81</id>
        <lastUpdateDate>2012-11-08T14:45:36.263+01:00</lastUpdateDate>
        <objectId>oai:localhost:68</objectId>
        <processingPath/>
        <schemaId>oai_dc</schemaId>
        <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
        <sourceObjectLastModificationDate>2012-10-11T12:50:16+02:00</sourceObjectLastModificationDate>
    </header>
</record>

POST /records

Description

Inserts a new record. The URI to the new record is indicated in Content-Location header field.

Request content

Request content must be of type multipart/mixed consisting of record header encoded as application/xml and record binary data as application/octet-stream.

Header must contain the following elements:

  • objectId
  • sourceId
  • schemaId

The following elements may be included in header:

  • processingPath
  • sourceObjectLastModificationDate
  • lastProcessingDate

Sample record header:

<?xml version="1.0" encoding="UTF-8"?>
<header>
    <objectId>oai:localhost:8111</objectId>
    <schemaId>oai_dc</schemaId>
    <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
    <sourceObjectLastModificationDate>2012-10-21T11:37:22+02:00</sourceObjectLastModificationDate>
</header>

Status Codes

CodeDescription
204The record has been successfully created (no content is returned).
409The submitted data are incorrect.
500An internal server error has occurred.

Sample Call

curl -v -H "Content-Type: multipart/mixed" --form "fileupload=@record.xml" --form "fileupload=@record_data" -X POST http://localhost:8080/clepsydra-storage/rest/records

Sample Response

HTTP/1.1 204 No Content
Content-Location: http://localhost:8080/clepsydra-storage/rest/records/3154

PUT /records/{id}

Description

Modifies the record with given id.

Path elements

Path elementTypeDescription
idIntegerrecord identifier

Request content

Request content must be of type multipart/mixed consisting of record header encoded as application/xml and record binary data as application/octet-stream.

Header may contain the following elements:

  • sourceObjectLastModificationDate

Sample record header:

<?xml version="1.0" encoding="UTF-8"?>
<header>
    <sourceObjectLastModificationDate>2012-10-21T11:37:22+02:00</sourceObjectLastModificationDate>
</header>

Status Codes

CodeDescription
204The record has been successfully updated (no content is returned).
404The record with the given {id} does not exist.
409The submitted data are incorrect.
500An internal server error has occurred.

Sample Call

curl -H "Content-Type: multipart/mixed" --form "fileupload=@record.xml" --form "fileupload=@record_data" -X PUT http://localhost:8080/clepsydra-storage/rest/records/81

Sample Response

HTTP/1.1 204 No Content

DELETE /records/{id}

Description

Marks the record with the identifier {id} as deleted.

Path elements

Path elementTypeDescription
idIntegerrecord identifier

Status Codes

CodeDescription
204The record has been successfully marked as deleted (no content is returned).
404The record with the given {id} does not exist.
500An internal server error has occurred.

Sample Call

curl -X DELETE http://localhost:8080/clepsydra-storage/rest/records/81

Sample Response

HTTP/1.1 204 No Content

POST /records/erase

Description

Permanently removes records that fulfil specified criteria. At least one of the parameters presented in the section below has to be passed in the request.

Parameters

ParamTypeRequiredDescription
sourceFromDateNosource object last modification date has to be greater than this value
sourceUntilDateNosource object last modification date has to be lower than this value
fromDateNolast modification date has to be greater than this value
untilDateNolast modification date has to be lower than this value
isProcessedBooleanNorecord has to be processed
schemaIdStringNoschema identifier has to be equal to this value
sourceIdStringNosource identifier has to be equal to this value
objectIdStringNoobject identifier has to be equal to this value
isDeletedBooleanNorecord has to be marked as deleted
thresholdIdIntegerNorecord identifier has to be greater than this value
fbcIdStringNofbc identifier
appearanceFromDateNoappearance date has to be lower than this value
appearanceUntilDateNoappearance date has to be greater than this value

Status Codes

CodeDescription
204The records have been successfully removed (no content is returned).
400The request does not provide a value for any of the parameters.
500An internal server error has occurred.

Sample Call

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" --data "schemaId=mets" http://localhost:8080/clepsydra-storage/rest/records/erase

Sample Response

HTTP/1.1 204 No Content

POST /records/{id}/erase

Description

Permanently removes the record with the identifier {id}.

Path elements

Path elementTypeDescription
idIntegerrecord identifier

Status Codes

CodeDescription
204The record has been successfully removed (no content is returned).
404The record with the given {id} does not exist.
500An internal server error has occurred.

Sample Call

curl -X POST 'http://localhost:8080/clepsydra-storage/rest/records/81/erase'

Sample Response

HTTP/1.1 204 No Content

Resource /headers

GET /headers

Description

Searches for record headers using specified parameters. Returns an XML document with the root element <headerQueryResult>. All the headers are enclosed in the <headers> tags within <headerQueryResult> and every header is enclosed in the <header> tags within <headers>. Headers contain all fields from records except for the <data> field.

The results are paged. The default limit is set to 200 headers per page. One may change the limit by setting the pl.psnc.synat.a9.ms.rest.recordsListSize property of the Jersey Web Application servlet in the web.xml file. Every page is an XML document. If the number of headers exceeds the limit, the document contains the element <nextPageToken> within <headerQueryResult>. The content of the <nextPageToken> may be passed as a value of the token parameter in the following request in order to obtain the next page.

Parameters

ParamTypeRequiredDescription
sourceFromDateNosource object last modification date has to be greater than this value
sourceUntilDateNosource object last modification date has to be lower than this value
fromDateNolast modification date has to be greater than this value
untilDateNolast modification date has to be lower than this value
isProcessedBooleanNorecord has to be processed
schemaIdStringNoschema identifier has to be equal to this value
sourceIdStringNosource identifier has to be equal to this value
objectIdStringNoobject identifier has to be equal to this value
isDeletedBooleanNorecord has to be marked as deleted
tokenStringNoretrieves results for the specified token
thresholdIdIntegerNorecord identifier has to be greater than this value
fbcIdStringNofbc identifier
appearanceFromDateNoappearance date has to be lower than this value
appearanceUntilDateNoappearance date has to be greater than this value

Status Codes

CodeDescription
200The headers have been successfully retrieved.
404The page for the given token is not found.
500An internal server error has occurred.

Sample Call

curl -X GET 'http://localhost:8080/clepsydra-storage/rest/headers?from=2012-10-24T16:40:16Z&until=2012-11-08T15:45:38Z'

Sample Response

<headerQueryResult>
    <expirationDate>2013-02-11T17:01:51.017+01:00</expirationDate>
    <nextPageToken>81ccdff4-10e3-4092-b162-14e0a7b452f3</nextPageToken>
    <token>c823a5e3-2bfe-4480-b756-b96813f664c0</token>
    <headers>
        <header>
            <appearanceDate>2012-11-08T14:45:31.765+01:00</appearanceDate>
            <checksum>d41d8cd98f00b204e9800998ecf8427e</checksum>
            <fbcId>nnnnnnh</fbcId>
            <id>1</id>
            <lastUpdateDate>2012-11-08T14:45:31.719+01:00</lastUpdateDate>
            <objectId>oai:localhost:81</objectId>
            <processingPath/>
            <schemaId>oai_dc</schemaId>
            <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
            <sourceObjectLastModificationDate>2012-10-12T11:37:22+02:00</sourceObjectLastModificationDate>
        </header>
        <header>
            <appearanceDate>2012-11-08T14:45:31.765+01:00</appearanceDate>
            <checksum>d41d8cd98f00b204e9800998ecf8427e</checksum>
            <fbcId>nnnnnnc</fbcId>
            <id>2</id>
            <lastUpdateDate>2012-11-08T14:45:31.719+01:00</lastUpdateDate>
            <objectId>oai:localhost:109</objectId>
            <processingPath/>
            <schemaId>oai_dc</schemaId>
            <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
            <sourceObjectLastModificationDate>2012-10-24T16:43:16+02:00</sourceObjectLastModificationDate>
        </header>
    </headers>
</headerQueryResult>

GET /headers/{id}

Description

Retrieves the header of the record with the identifier {id}. The header contains all fields from the record except for the <data> field.

Path elements

Path elementTypeDescription
idIntegerrecord identifier

Status Codes

CodeDescription
200The header has been successfully retrieved.
404The header with the given {id} does not exist.
500An internal server error has occurred.

Sample Call

curl -X GET http://localhost:8080/clepsydra-storage/rest/headers/81

Sample Response

<header>
    <appearanceDate>2012-11-08T14:45:36.264+01:00</appearanceDate>
    <checksum>7f3482932d78f0a1812e06ce69d6b9be</checksum>
    <fbcId>nnnnnhV</fbcId>
    <id>81</id>
    <lastUpdateDate>2012-11-08T14:45:36.263+01:00</lastUpdateDate>
    <objectId>oai:localhost:68</objectId>
    <processingPath/>
    <schemaId>oai_dc</schemaId>
    <sourceId>http://localhost/dlibra/oai-pmh-repository.xml</sourceId>
    <sourceObjectLastModificationDate>2012-10-11T12:50:16+02:00</sourceObjectLastModificationDate>
</header>

Resource /counts

GET /counts

Description

Returns the number of records that fulfil the specified criteria.

Parameters

ParamTypeRequiredDescription
isProcessedBooleanNorecord has to be processed
schemaIdStringNoschema identifier has to be equal to this value
sourceIdStringNosource identifier has to be equal to this value
isDeletedBooleanNorecord has to be marked as deleted

Status Codes

CodeDescription
200The record count has been successfully retrieved.
500An internal server error has occurred.

Sample Call

curl -X GET 'http://localhost:8080/clepsydra-storage/rest/counts?schemaId=oai_dc&isProcessed=false'

Sample Response

408499