Clepsydra Storage - REST API Documentation

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

Param	Type	Description
id	Long	record identifier
fbcId	String	flexible backward compatible identifier
objectId	String	object identifier
schemaId	String	schema identifier
sourceId	String	source identifier
processingPath	String	processing path
sourceObjectLastModificationDate	Date	source object last modification date
lastUpdateDate	Date	last update date
deleteDate	Date	delete date
lastProcessingDate	Date	last processing date
checksum	String	checksum
appearanceDate	Date	appearance date

Resources

/records
/headers
- GET /headers
- GET /headers/{id}
/counts
- GET /counts

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

Param	Type	Required	Description
sourceFrom	Date	No	source object last modification date has to be greater than this value
sourceUntil	Date	No	source object last modification date has to be lower than this value
from	Date	No	last modification date has to be greater than this value
until	Date	No	last modification date has to be lower than this value
isProcessed	Boolean	No	record has to be processed
schemaId	String	No	schema identifier has to be equal to this value
sourceId	String	No	source identifier has to be equal to this value
objectId	String	No	object identifier has to be equal to this value
isDeleted	Boolean	No	record has to be marked as deleted
token	String	No	retrieves results for the specified token
thresholdId	Integer	No	record identifier has to be greater than this value
fbcId	String	No	fbc identifier
appearanceFrom	Date	No	appearance date has to be lower than this value
appearanceUntil	Date	No	appearance date has to be greater than this value

Status Codes

Code	Description
200	The records have been successfully retrieved.
404	The page for the given token is not found.
500	An 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 element	Type	Description
id	Integer	record identifier

Status Codes

Code	Description
200	The record has been successfully retrieved.
404	The record with the given `{id}` does not exist.
500	An 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

Code	Description
204	The record has been successfully created (no content is returned).
409	The submitted data are incorrect.
500	An 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 element	Type	Description
id	Integer	record 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

Code	Description
204	The record has been successfully updated (no content is returned).
404	The record with the given `{id}` does not exist.
409	The submitted data are incorrect.
500	An 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 element	Type	Description
id	Integer	record identifier

Status Codes

Code	Description
204	The record has been successfully marked as deleted (no content is returned).
404	The record with the given `{id}` does not exist.
500	An 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

Param	Type	Required	Description
sourceFrom	Date	No	source object last modification date has to be greater than this value
sourceUntil	Date	No	source object last modification date has to be lower than this value
from	Date	No	last modification date has to be greater than this value
until	Date	No	last modification date has to be lower than this value
isProcessed	Boolean	No	record has to be processed
schemaId	String	No	schema identifier has to be equal to this value
sourceId	String	No	source identifier has to be equal to this value
objectId	String	No	object identifier has to be equal to this value
isDeleted	Boolean	No	record has to be marked as deleted
thresholdId	Integer	No	record identifier has to be greater than this value
fbcId	String	No	fbc identifier
appearanceFrom	Date	No	appearance date has to be lower than this value
appearanceUntil	Date	No	appearance date has to be greater than this value

Status Codes

Code	Description
204	The records have been successfully removed (no content is returned).
400	The request does not provide a value for any of the parameters.
500	An 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 element	Type	Description
id	Integer	record identifier

Status Codes

Code	Description
204	The record has been successfully removed (no content is returned).
404	The record with the given `{id}` does not exist.
500	An 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

Param	Type	Required	Description
sourceFrom	Date	No	source object last modification date has to be greater than this value
sourceUntil	Date	No	source object last modification date has to be lower than this value
from	Date	No	last modification date has to be greater than this value
until	Date	No	last modification date has to be lower than this value
isProcessed	Boolean	No	record has to be processed
schemaId	String	No	schema identifier has to be equal to this value
sourceId	String	No	source identifier has to be equal to this value
objectId	String	No	object identifier has to be equal to this value
isDeleted	Boolean	No	record has to be marked as deleted
token	String	No	retrieves results for the specified token
thresholdId	Integer	No	record identifier has to be greater than this value
fbcId	String	No	fbc identifier
appearanceFrom	Date	No	appearance date has to be lower than this value
appearanceUntil	Date	No	appearance date has to be greater than this value

Status Codes

Code	Description
200	The headers have been successfully retrieved.
404	The page for the given token is not found.
500	An 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 element	Type	Description
id	Integer	record identifier

Status Codes

Code	Description
200	The header has been successfully retrieved.
404	The header with the given `{id}` does not exist.
500	An 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

Param	Type	Required	Description
isProcessed	Boolean	No	record has to be processed
schemaId	String	No	schema identifier has to be equal to this value
sourceId	String	No	source identifier has to be equal to this value
isDeleted	Boolean	No	record has to be marked as deleted

Status Codes

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

Sample Call

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