IntakeService REST APIs - Release v0.1

Owned by Jessi Weithman
Apr 18, 2024
7 min read
Intake Service Home

Brief Description

For a full desciption, visit the Service Description and Assumptions page.

Assumptions

For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Object Entry Requirements
Intake Service Description and Assumptions
Intake Service Entity Diagrams

REST-based API

The Intake Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Intakes.

In this API, there is also an operation to retrieve a list with summary information about all Intake records. The IDs returned in that list can be used in the aforementioned CRUD operations.

List All Intakes

Description

Gets summary information about all Intake records. This includes the CollectionSpace ID (csid) of each intake, which can be included in the URIs of subsequent requests in order to read, update, or delete specific intake records.

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

GET /cspace-services/intakes/ HTTP/1.1

To do this via a web browser:

http://demo.collectionspace.org:8180/cspace-services/intakes/

To do this via the 'curl' command-line utility:

curl http://demo.collectionspace.org:8180/cspace-services/intakes/

Example: Success response

On success, a response with a "200 OK" HTTP status code, followed by a list containing summary information for each of the existing Intake records, if any, is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:intake-list>
	<intake-list-item>
	<uri>/default/abf52fbc-0471-4f3b-b1b1-c186bb79c44d</uri>
	<csid>abf52fbc-0471-4f3b-b1b1-c186bb79c44d</csid>
	</intake-list-item>
	<intake-list-item>
	<uri>/default/9eb9f43e-95fe-417b-aefc-a44d0f38d3cb</uri>
	<csid>9eb9f43e-95fe-417b-aefc-a44d0f38d3cb</csid>
	</intake-list-item>
	<intake-list-item>
	<uri>/default/78981343-12bb-4a55-ace7-fad6dd8280e0</uri>
	<csid>78981343-12bb-4a55-ace7-fad6dd8280e0</csid>
	</intake-list-item>
	<intake-list-item>
	<uri>/default/a368c2df-b7c5-47db-99ce-88f1367b7d33</uri>
	<csid>a368c2df-b7c5-47db-99ce-88f1367b7d33</csid>
	</intake-list-item>
</ns2:intake-list>

If no Intake records are found, a response with a "200 OK" HTTP status code, followed by an empty list, is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:intake-list xmlns:ns2="http://services.collectionspace.org/intake"/>

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

Create a Intake

Description

Creates a new Intake record. Assigns a unique, service-specified CollectionSpace ID (csid) to that Intake record.

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

POST /cspace-services/intakes HTTP/1.1
Content-Type: application/xml

with an entity body containing a valid XML representation of a Intake; e.g.:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:intake xmlns:ns2="http://services.collectionspace.org/intake">
    <currentOwner></currentOwner>
    <depositor></depositor>
    <depositorsRequirements></depositorsRequirements>
    <entryDate>updated-entryDate-1246391492901</entryDate>
    <entryMethod></entryMethod>
    <entryNote></entryNote>
    <entryNumber>updated-entryNumber-1246391492901</entryNumber>
    <entryReason></entryReason>
    <packingNote></packingNote>
    <returnDate></returnDate>
</ns2:intake>

To do this via the 'curl' command-line utility:

curl -X POST -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8180/cspace-services/intakes/ -T - < {data}

(The "-T -" parameter above specifies that the body of the request will come from standard input.)

Or, alternately:

curl -X POST -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8180/cspace-services/intakes -T {filename or path to file containing data}

(Note that in this alternate request using 'curl', there should not be a closing slash at the end of the name of the container to which the new Intake record is to be added; e.g. end your URL with "intakes', not "intakes/". That is because at least some versions of curl appear to append the name of the file being uploaded to the URL, following a closing slash.)

Where {data} or {filename or path to file containing data} is a valid XML representation of a Intake, provided via standard input or stored in a text file, respectively.

In both instances, the "-H "Content-Type: application/xml" is required; this adds a "Content-Type: application/xml" header line to the request headers.

Example: Success response

On success, a response with a "201 Created" HTTP status code is returned:

HTTP/1.1 201 Created
Content-Type: application/xml
Content-Length: nnnn
...

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

Read a Intake

Description

Gets (reads) information about a single Intake record, specified by its CollectionSpace ID (csid).

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

GET /cspace-services/intakes/{id} HTTP/1.1

To do this via a web browser:

http://demo.collectionspace.org:8180/cspace-services/intakes/{id}

To do this via the 'curl' command-line utility:

curl http://demo.collectionspace.org:8180/cspace-services/intakes/{id}

Where {id} is a CollectionSpace ID (csid), such as 59242af0-0463-4fb2-af0d-2467186c28480. To identify the ID of a specific document, List All Intakes or check the response from a request to Create a Intake.

Example: Success response

On success, a response with a "200 OK" HTTP status code and a representation of the requested Intake record is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:intake xmlns:ns2="http://services.collectionspace.org/intake">
    <currentOwner>Ron McDonald</currentOwner>
    <depositor>Peter Wolf</depositor>
    <depositorsRequirements>Reserve ownership.</depositorsRequirements>
    <entryDate>12-02-2009</entryDate>
    <entryMethod>Manual</entryMethod>
    <entryNote>Needs restoration</entryNote>
    <entryNumber>1246391492901</entryNumber>
    <entryReason>None given</entryReason>
    <packingNote>None</packingNote>
    <returnDate>12-30-2009</returnDate>
</ns2:intake>

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

As of 2009-04-14 19:42-700, this call, when used with a non-existent csid, currently returns an empty Intake record element with no child elements and a 200 OK status code, rather than a 404 Not Found status code.

Update a Intake

Description

Updates an individual Intake record, specified by its CollectionSpace ID (csid). Accepts a updated Intake record in the body of the request. Replaces the values of the existing Intake record's fields (elements) with any non-empty values provided in the updated Intake record. Empty fields in the updated Intake record are ignored.

Subsequent releases may provide more intelligent merging during updates, and/or more client control over how merges are performed.

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

PUT /cspace-services/intakes/{id} HTTP/1.1
Content-Type:application/xml

with an entity body containing a valid XML representation of a Intake; e.g.:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:intake xmlns:ns2="http://services.collectionspace.org/intake">
    <currentOwner>Ron McDonald</currentOwner>
    <depositor>Peter Wolf</depositor>
    <depositorsRequirements>Reserve ownership.</depositorsRequirements>
    <entryDate>12-02-2009</entryDate>
    <entryMethod>Manual</entryMethod>
    <entryNote>Needs restoration</entryNote>
    <entryNumber>1246391492901</entryNumber>
    <entryReason>None given</entryReason>
    <packingNote>None</packingNote>
    <returnDate>12-30-2009</returnDate>
</ns2:intake>

To do this via the 'curl' command-line utility:

curl -X PUT -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8180/cspace-services/intakes/{id} -T - < {data}

(The "-T -" parameter above specifies that the body of the request will come from standard input.)

Or, alternately:

curl -X PUT -H "Content-Type: application/xml" \
http://demo.collectionspace.org:8180/cspace-services/intakes/{id} \
-T {filename or path to file containing data}

Where {id} is a CollectionSpace ID (csid), such as 59242af0-0463-4fb2-af0d-2467186c28480. To identify the ID of a specific document, List All Intakes or check the response from a request to Create a Intake.

Where {data} or {filename or path to file containing data} is a valid XML representation of a Intake, provided via standard input or stored in a text file, respectively.

In both instances, the "-H "Content-Type: application/xml" is required; this adds a "Content-Type: application/xml" header line to the request headers.

Example: Success response

On success, a response with a "200 OK" HTTP status code and a representation of the updated Intake record is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:intake xmlns:ns2="http://services.collectionspace.org/intake">
    <currentOwner>Ron McDonald</currentOwner>
    <depositor>Peter Wolf</depositor>
    <depositorsRequirements>Reserve ownership.</depositorsRequirements>
    <entryDate>12-02-2009</entryDate>
    <entryMethod>Manual</entryMethod>
    <entryNote>Needs restoration</entryNote>
    <entryNumber>1246391492901</entryNumber>
    <entryReason>None given</entryReason>
    <packingNote>None</packingNote>
    <returnDate>12-30-2009</returnDate>
</ns2:intake>

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

As of 2009-04-15 19:30-700, this call, when used with a csid that does not match that of any existing Intake record, returns a 200 OK status code. We'll need to verify whether this is desired behavior; it may be the case that a PUT to a non-existent csid does not actually create a new document, using Nuxeo's Restlet-based API.

Delete a Intake

Description

Deletes a single Intake record, specified by its CollectionSpace ID (csid).

Authentication

In Release 0.1, no authentication credentials are requested by the service.

The service currently performs its own internal authentication, using HTTP Basic authentication, to Nuxeo's REST-based API. This will change in subsequent service releases.

Arguments

This service call currently does not accept query parameters or other arguments.

Example: Request

Send this HTTP request:

DELETE /cspace-services/intakes/{id} HTTP/1.1

To do this via the 'curl' command-line utility:

curl -X DELETE http://demo.collectionspace.org:8180/cspace-services/intakes/{id}

Where {id} is a CollectionSpace ID (csid), such as 59242af0-0463-4fb2-af0d-2467186c28480. To identify the ID of a specific document, List All Intakes or check the response from a request to Create a Intake.

Example: Success response

On success, a response with a "200 OK" HTTP status code is returned:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: nnnn
...

Error Codes

To determine if an error occurred, check the HTTP Status Code that is returned in the response's HTTP headers. Any non 2xx status code represents an error condition.

Nearly every HTTP client library or framework will offer a call that allows you to easily examine the status code of the response. In 'curl', you can dump to a file the HTTP headers that you receive in a response, by adding the '-D {filename}' parameter to your request.

As of 2009-04-14 19:45-700, this call, when used with a non-existent csid, currently returns a 204 No Content status code, rather than a 404 Not Found status code.