REST API: CRUD

Table of Contents

• Asset CRUD
  • Create
  • Relationship Search
• FileSet CRUD
  • Update or Create
  • Retrieve Derivative

All the methods described below require simple HTTP authentication as an API user. Some methods require an API admin identity.

Asset CRUD

Create

Request URI

POST /api/ingest/<model>

Creates an individual asset with one or more files.

<model> is a string whose value corresponds to the Sufia model to be created, e.g. StillImage.

Request Body Parameters

Parameters not defined in the following list will be ignored.

• metadata (multi-part field): Asset metadata. Property names follow the LAKEshore field names. Property values are enclosed in lists if they are multi-valued. E.g. single valued property: metadata[uid]=SI-12345; multi valued property: metadata[comment][]=This is one of many comments. To add multiple values, simply add separate metadata[<multi_value_field_name>][]=<value> to the request.
• content[<name>] (bitstream | URL): Content of asset instance. The variable name is the name of the instance. If the value is a URL, the resource is fetched and ingested in the repository. The original file is mandatory. Currently only directly uploaded bitstreams are supported.
• ref_content[<name>] (URL): URL of externally referenced asset instance. The content will NOT be ingested but rather referenced in the repository. Currently not supported.
• sharing (JSON object): user- and group-level permissions. See below for syntax definition of this field.
• duplicate_check: (boolean, defaults to true): whether to perform duplicate check on existing resources.

<name>: designates a particular role for each file. original, pres_master and intermediate are the supported values. Alternatively, numeric values indicate additional instances with no defined role. At least one file with the original role should be present.

Mandatory fields

• metadata[document_type_uri]: At least a top level document type must be specified.
• metadata[depositor]: this sets the “depositor” and “created by department” values (unless metadata[dept_created] is also specified—see below)
• metadata[pref_label]

Fields with special behavior

• metadata[uid]: if provided, LAKEshore will use this for the aic:uid property, which is used to generate the resource URI. If absent, the UID will be generated by the default minting service.
• metadata[dept_created]: if provided, LAKEshore will use this for the aic:deptCreated property (depositor’s department). If absent, the department is set to the depositor’s current department.
• metadata[visibility] (string): one of open, authenticated or department. Defaults to department.
• metadata[on_behalf_of] (string): LAKEshore will set the asset's depositor to this param. Also, an edit permission will be created for this user's department.

Relationships

• metadata[representations_for][]: UUID (MD5 hash from Fedora URI) of resource(s) that this asset is representation of.
• metadata[documents_for][]: UUID (MD5 hash from Fedora URI) of resource(s) that this asset is documentation of.
• metadata[attachments_for][]: UUID (MD5 hash from Fedora URI) of asset(s) attached to this asset. (@FIXME - this field name should be flipped with the one below, probably a leftover of mine #1708)
• metadata[attachment_uris][]: URI of asset(s) that this asset is attachment of (@FIXME - this should be a UUID like the others, and also flip field name with the previous as mentioned above).

Other common fields

See the LAKE content model document for a comprehensive list.

• metadata[alt_label][]: alternative label(s) (skos:altLabel).
• metadata[description][]: description(s) (dcterm:description).
• metadata[publish_channel_uris][]: URI of publish channel(s) for the asset. See authority reference for URIs.

Sharing Parameters

sharing is a list of JSON documents, e.g.:

[<acl1>, <acl2>, [,...]]

Where each ACL is defined as follows:

{"type" : "<agent type>", "name" : "<uid>", "access" : "<access type>"}

Where:

• <agent type> is one of group (AIC department) or person (AIC user)
• <uid> is the logon (nick) of a user or the numeric ID of a department
• <access type> is one of read or edit

Response Code

202 Accepted

This means that the creation job has started, not that the asset has been successfully created. If the creation, which is asynchronous, fails, an error will be logged separately.

409 Conflict

If the checksum any of the uploaded files already exists in the repository.

400 Bad Request

If some mandatory metadata are missing, metadata validation fails or any other exception is raised by Sufia. An informative message should be added to the response body to indicate what failed.

Response Headers

Location: URI of new resource in LAKEshore.

Restrictions

1. The sharing parameter must refer to an "active" user. This is a user with an RDF type of aic:ActiveUser in Fedora. If a non-active or non-existing user is used, the API throws an error.
2. metadata[uid] cannot be an existing UID.

Request Example

The following request, using curl, creates an asset with four instances: original, intermediate, preservation master and a one-off derivative with no role. The resource is only visible by the user's department. User jdoe99 is able to view and modify the resource, IS department (ID #112) can view the resource.

NOTE: the HTTP authentication parameter refers to the API client identity, which is not related with the depositor that the API is acting on behalf of.

curl -X POST \
-u 'username:password' \
-F 'metadata[uid]=SI-G253234' \
-F 'metadata[legacy_uid][]=G253234' \
-F 'metadata[legacy_uid][]=another_ID_from some_other_app' \
-F 'metadata[citi_uid]=12324' \
-F 'metadata[document_type_uri]=http://definitions.artic.edu/doctypes/Imaging' \
-F 'content[original]=@img1_original.dng' \
-F 'content[pres_master]=@img1_pres.tiff' \
-F 'content[intermediate]=@img1_intermediate.tiff' \
-F 'content[0]=@img1_oddball_deriv.jpg' \
-F 'metadata[depositor]=laketest' \
-F 'duplicate_check=true' \
-F 'metadata[visibility]=department' \
-F 'sharing=[{"type" : "group", "name" : "112", "access" :
"read"}, {"type" : "person", "name" : "jdoe99", "access" :
"edit"}]' \
\
'https://myrepo.edu/api/ingest/StillImage'

Relationship Search

Show a search results page with assets related to an arbitrary list of non-assets.

This is technically not an API method since it returns an HTML page, but it is convenient to list it here.

Notes:

1. Currently only one relationship at a time can be queried. Later releases may allow multiple relationships to be specified.
2. While an arbitrary number of PKeys can be passed to the POST request, it is recommended to limit the number to 200 while the feature is initially used in a production setup. Also, modifying the search results via facets, sorting or changing page size will use a GET request, which may run into URL length limitations on Internet Explorer. The 200 PKey limit should keep the URL length within a safe range in this case.

Request

[GET | POST] /assets/search

Request parameters

• model: one of Agent, Exhibition, Place, Shipment, Transaction, Work
• resource_id: comma-separated list of CITI identifiers (PKeys)
• relationship_type: one of hasDocumentation, hasRepresentation, hasPreferredRepresentation

File Sets CRUD

Update or Create

Request URI

PUT /api/assets/<asset_uuid>/file_sets/<file_set role>

Where:

• <asset_uuid> is the asset's global identifier in XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX hex notation (RFC 4122)
• <file_set role> must be one of the following:
  • intermediate
  • original
  • preservation
  • legacy

Updates an existing file_set with a new file, or creates a file_set for given role, if one does not exist.

Parameters

The PUT body must be in MIME multipart/form-data format (RFC7578). It accepts the following Content-Disposition parameter "name" values:

The following is required:

• depositor
  • The nick of the AICUser, in LAKE, which sets the depositor.
  • Content-Type: text/plain; charset=us-ascii as this is the default the Content-Type may be omitted.
• file_set[files][]
  • The "filename" parameter should also be supplied in the Content-Disposition.
  • Content-Type: application/octet-stream
  • Content of file_set's binary file.
  • Only accepts one file but array / indexed list is required.

Response Codes

The update request was successful:

200 OK

The create request was successful:

201 OK

Request Example

The following request, using cURL, updates an existing file_set's binary.

curl -i -u username:password -X PUT\
 -F 'depositor=laketest'\
 -F 'file_set[files][]=@spec/fixtures/sun.png'\
 http://localhost:3000/api/assets/4f622807-720c-4f88-a047-eb0eb55ee375/file_sets/intermediate

Retrieve Derivative

Request URI

GET /downloads/<fileset ID>

Request parameters

• file (string): name of the derivative to retrieve. It can be one of: accessMaster, thumbnail, citiThumbnail, citiLarge.
• on_behalf_of: ID (nick) of the user on whose behalf the derivative is being requested. This works if the request is made by an API user with admin privileges. If empty, it default to the API user. If a valid user is specified, permissions are applied for that user and a 403 is issued is the user is not allowed to retrieve the resource.

Status Code

200 OK

The request body is the binary content of the derivative.

404 Not Found

If the derivative is not found. This is expected for some asset types (e.g. audio or dataset have no thumbnail). It is up to the client to establish how to handle this, e.g. providing a fallback image or issuing a warning depending on the context.

403 Forbidden

If the API user or the user secified with on_behalf_of is not authorized to retrieve the derivative.

Note: Currently, due to a bug that has been reported, a non-existing derivative returns a 401 Unauthorized instead.