Note: our current recommendation for clients who wish to interact with Cordra using HTTP is DOIP API for HTTP Clients. The older Cordra HTTP API described here is still supported and this documentation can still serve as a reference for certain Cordra behaviors independent of the particular API used to access Cordra.
Cordra provides a RESTful HTTP API for interacting with digital objects. Cordra also provides a web browser based interface that dynamically creates object editors based on configured Schemas/Types, mainly for administrative purposes.
Cordra HTTP requests that conform to HTTP/1.1 and HTTP/2 specifications (RFCs 7230, 7231, and 7540) are tested.
Main APIs
Resource |
Description |
|---|---|
Retrieves an object or part of an object by id. |
|
Create an object by type. |
|
Update an object by id. |
|
Search for objects (requires Cordra v2.1.0). |
|
Search for objects (requires Cordra v2.1.0). |
|
Search for objects. |
|
Delete an object by id. |
|
Delete a payload by id and name. |
|
Retrieves an object via the Handle proxy. |
|
Retrieve the ACLs for a specific object. |
|
Modify the ACLs for a specific object. |
|
Change the password of the currently authenticated user. |
|
Retrieve information about provided credentials. |
|
Call a Type method. (Some Type methods may allow the use of GET rather than POST.) |
|
List Type methods. |
|
Batch upload objects. |
Access Token APIs
Resource |
Description |
|---|---|
Create a new access token. |
|
Retrieve information about the specified access token. |
|
Delete specified access token (used to “sign out”). |
Administrative APIs
Resource |
Description |
|---|---|
Get schema or all schemas. |
|
Create or update a schema. |
|
Delete a schema. |
|
Bulk upload of objects from a json file. |
|
Change the password for the admin user. |
|
Update all handle records for objects in Cordra. |
|
Get status of handle update. |
|
Reindex all specified objects. |
|
Accessible even after failed startup to indicate success or failure |
Experimental APIs
Resource |
Description |
|---|---|
Get version information for a specific object. |
|
Create a version of a specific object. |
HTTP Response Code |
Description |
|---|---|
200 OK |
The request was successfully processed. |
400 Bad Request |
There was an error with the request, such as a creation or update which is not schema-valid. |
401 Unauthorized |
Actually “Unauthenticated”. There is no authenticated user, or authentication failed, but the requested operation requires authentication. |
403 Forbidden |
The authenticated user does not have permissions to perform the requested operation. |
404 Not Found |
The Cordra object or requested part does not exist. |
409 Conflict |
An attempt was made to create a Cordra object with a handle already in use by a Cordra object. |
500 Internal Server Error |
An unexpected server error occurred. Usually diagnosis requires looking at the server logs. |
Range requests for payloads can additionally return 206 Partial Content and 416 Range Not Satisfiable, following the standard specification for HTTP range requests.
For any Cordra API call that requires authentication, you can either authenticate directly for the single call, or provide an access token. Access tokens are used to maintain a server session in between requests. This way, the server does not need to reprocess your authentication credentials with each request. Using sessions can significantly speed up the process of making multiple requests.
There are two ways to authenticate directly. One is to include username (or, user object id) and password following the HTTP Basic Authentication method. Another is to authenticate using public-private key pair following the HTTP Bearer Authentication method with a JWT. For more information on the topic, see Authentication and Access Controls.
To obtain an access token, you must authenticate using the Access Token API. Once authenticated, you will receive an access token that should be sent back with subsequent calls. This token should be sent using an Authorization Bearer header. For example:
Authorization: Bearer ACCESS_TOKEN
The As-User header can be set to allow the admin user to perform operations on behalf of another user. If request comes with proper authentication for admin, and the As-User header is set, that userId will be considered to have authenticated instead.
The Authenticate Hook hook can optionally be used to allow broader non-admin access to As-User functionality.
All requests allow a query parameter called requestContext. This must be valid JSON object (suitably encoded
as a query parameter or, when building call requests, as an attribute). The requestContext is made available to JavaScript methods and lifecycle hooks as part of the
context argument (see Type Methods and Lifecycle Hooks). It is also made available to the StorageChooser used
with Multiple Storages.
In the following examples the schema shown below was added to the server
as type Document. Multiple types can be added. The server will only
accept POST and PUT requests for objects that conform to the schema
corresponding to the object type; other requests will receive a 400 Bad
Request response.
Example Schema:
{
"type": "object",
"title": "Document",
"required": [
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"cordra": {
"type": {
"autoGeneratedField": "handle"
}
}
},
"name": {
"type": "string",
"maxLength": 128,
"title": "Name"
},
"description": {
"type": "string",
"title": "Description"
},
"creator": {
"type": "object",
"title": "Creator",
"properties": {
"fullName": {
"type": "string",
"title": "Full Name"
},
"organization": {
"type": "string",
"title": "Organization"
}
}
}
}
}
Request:
GET /objects/<id>
Parameters |
||
|---|---|---|
id |
required |
The id of the desired object. |
jsonPointer |
optional |
The jsonPointer into the subcomponent of the target object |
filter |
optional |
A JSON array of jsonPointers used to restrict the result object. |
payload |
optional |
The name of the payload to retrieve |
pretty |
optional |
Format returned json |
text |
optional |
When present on a request which would normally result in a JSON string, the response is the contents of the JSON string |
disposition |
optional |
For payload requests. Can be used to set the Content-Disposition header on the response; “disposition=attachment” will cause a standard web browser to perform a download operation |
full |
optional |
If present the response is the full Cordra object, including properties id, type, content, acl, metadata, and payloads. By default only the content is returned. |
Request headers |
||
|---|---|---|
Range |
optional |
If present in a payload request, only retrieve the requested bytes from the payload. |
Response headers |
|
|---|---|
X-Schema |
Type of the object |
X-Permission |
What the calling user is authorized to do with object. READ or WRITE. Any caller with WRITE permission is also permitted to read the object. |
Request:
GET /objects/20.5000.1234/1321d2d033b22bee1187
Response:
{
"id" : "20.5000.1234/1321d2d033b22bee1187",
"name" : "A file",
"description" : "It's a file",
"creator" : {
"fullName" : "John Doe",
"organization" : "Acme Corp."
}
}
Request:
GET /objects/20.5000.1234/1321d2d033b22bee1187?jsonPointer=/creator
Response:
{
"fullName" : "John Doe",
"organization" : "Acme Corp."
}
Request:
GET /objects/20.5000.1234/1321d2d033b22bee1187?jsonPointer=/description&text
Response:
It's a file
Request:
GET /objects/20.5000.1234/1321d2d033b22bee1187?payload=file
Response:
(Contents of the payload)
To retrieve the Cordra design object, retrieve the object with id “design”.
Request:
POST /objects/?type=Document
Parameters |
||
|---|---|---|
type |
required |
The type of the object being created. In this case “Document”. |
dryRun |
optional |
Do not actually create the object. Will return results as if object had been created. |
suffix |
optional |
The suffix of the handle used to identify this object. One will be generated if neither ‘suffix’ nor ‘handle’ is specified. |
handle |
optional |
The handle used to identify this object. One will be generated if neither ‘suffix’ nor ‘handle’ is specified. |
full |
optional |
If present the response is the full Cordra object, including properties id, type, content, acl, metadata, and payloads. By default only the content is returned. |
See Handle Minting Configuration for configuring the handle prefix for automatic handle generation when the “handle” parameter is not used.
Request Headers |
|
|---|---|
Content-Type |
application/json OR multipart/form-data |
Response Headers |
|
|---|---|
Location |
URI for accessing the created object; includes the id of the created object |
POST Data:
{
"id" : "",
"name" : "A different file",
"description" : "This one doesn't contain a file",
"creator" : {
"fullName" : "Jane Doe",
"organization" : "Acme Labs."
}
}
Response:
{
"id" : "20.5000.1234/23bdf2a62a83225a1b77",
"name" : "A different file",
"description" : "This one doesn't contain a file",
"creator" : {
"fullName" : "Jane Doe",
"organization" : "Acme Labs"
}
}
To create an object with one or more payloads, POST data of type
multipart/form-data must be sent. There must be one part named content
which is the JSON content of the object to be created.
There may optionally be a part named acl which will be the acl component
of the new object; it must be a JSON object with two properties "readers"
and "writers", each a JSON array of strings.
Parts which have filenames determine payloads. The payload name is the part name. The filename and a Content-Type if present are stored as the metadata of the payload.
POST Data:
--PART-SEPARATOR
Content-Disposition: form-data; name="content"
{
"id": "",
"name": "Really a file",
"description": "Really a file",
"file": ""
}
--PART-SEPARATOR
Content-Disposition: form-data; name="file"; filename="a.html"
Content-Type: text/html
...
--PART-SEPARATOR--
Request:
PUT /objects/<id>
Parameters |
||
|---|---|---|
id |
required |
The id of the object to update. |
dryRun |
optional |
Do not actually update the object. Will return results as if object had been updated. |
type |
optional |
If specified, indicates a request to change the type of the object. Note that schemas and lifecycle methods will change with the type; in many cases deleting and recreating an object may be preferable. |
payloadToDelete |
optional |
The name of an existing payload to delete. Can be used multiple times. |
jsonPointer |
optional |
A JSON pointer within the object’s content. Only the JSON at that JSON pointer will be updated. Note that only the content can be modified, not the full object. |
full |
optional |
If present the response is the full Cordra object, including properties id, type, content, acl, metadata, and payloads. By default only the content is returned. |
Request Headers |
|
|---|---|
Content-Type |
application/json OR multipart/form-data |
Request:
PUT /objects/20.5000.1234/23bdf2a62a83225a1b77
PUT Data:
{
"id" : "20.5000.1234/23bdf2a62a83225a1b77",
"name" : "A different file",
"description" : "I've changed the description",
"creator" : {
"fullName" : "Jane Doe",
"organization" : "Acme Labs."
}
}
Response:
{
"id" : "20.5000.1234/23bdf2a62a83225a1b77",
"name" : "A different file",
"description" : "I've changed the description",
"creator" : {
"fullName" : "Jane Doe",
"organization" : "Acme Labs."
}
}
When updating an object with payloads, existing payloads can be omitted
from the uploaded JSON data. Those payloads will be unchanged. New
payloads and modified payloads should be included as parts in a
multipart/form-data request, as for the object creation API.
Additionally a payload can be deleted by including its name as the
value of a payloadToDelete parameter. Multiple payloadToDelete
parameters are allowed.
Cordra v2.1.0 includes a separate /search API. For compatibility with earlier versions of Cordra, the GET /objects/?query=<query> API (with a query and no object ID) should be used.
The /search API supports POST of a JSON body defining the search request.
The /objects API only supports GET for searching, except POST with Content-Type: application/x-www-form-urlencoded
can be used to avoid URI length limitations.
Request:
GET /search
POST /search
GET /objects/?query=<query>
Parameters (or properties of application/json POST body) |
||
|---|---|---|
query |
optional |
The query to be processed. Either query or queryJson is required. |
queryJson |
optional |
JSON which is used to generate a query for all objects with content matching the supplied JSON. Either query or queryJson is required. |
ids |
optional |
If specified, the search returns the ids of the matched objects only. |
pageNum |
optional, default 0 |
The desired results page number. 0 is the first page. |
pageSize |
optional |
The number of results per page. If omitted or negative no limit. If 0 no results are returned, only the size (number of hits). |
sortFields |
optional |
Sort fields for the query results. A JSON array of objects with properties “name”, a JSON pointer, and optionally “reverse”, a boolean. (A legacy format is comma-separated, with each field name optionally followed by ASC or DESC to indicate the sort direction.) |
full |
optional |
If set to false only the content of the object is returned. |
filter |
optional |
A JSON array of jsonPointers used to restrict the result object. The jsonPointers are relative to the root of the objects in the results. Note that that root changes if the full param is set to false. |
filterQueries |
optional |
A JSON array of JSON strings, each of which is interpreted as a query string specifying additional constraints. Each item in filterQueries is conceptually added to the main query as with a boolean AND; however filterQueries do not affect document scoring, and in some cases may enhance backend performance by allowing caching. |
facets |
optional |
A JSON array of JSON objects. Each facet object must include a property “field”, value a string, which is an index field on which faceting is requested; the facet object may optionally include a property “maxBuckets”, the maximum number of buckets to return, which defaults to 10; see Faceted Search below. |
includeScore |
optional |
A boolean; if true, the “score” from the index service will be included in each Cordra object returned, as a property of “responseContext”. |
includeVersions |
optional |
A boolean; if true, Cordra version objects will be included in the results (see Digital Object Versioning) |
Request:
GET /search?query=file&pageNum=0&pageSize=10
Response:
{
"size": 1,
"pageNum": 0,
"pageSize": 10,
"results": [
{
"id": "20.5000.1234/1321d2d033b22bee1187",
"type": "Document",
"content": {
"id": "20.5000.1234/1321d2d033b22bee1187",
"name": "A file",
"description": "Its a file",
"file": "",
"creator": {
"fullName": "John Doe",
"organization": "Acme Corp."
}
}
}
]
}
The same request can be sent as POST with Content-Type: application/json
and this POST body:
{
"query": "file",
"pageNum": 0,
"pageSize": 10
}
The query format is that used by the indexing backend, which is generally the inter-compatible Lucene/Solr/Elasticsearch format for fielded search. The fields include the payload name for payloads, and modified JSON Pointers for components of the object JSON content, where array indices are replaced with “_” as a wildcard. Typical field names are “/id”, “/name”, “/creator/organization”, “/users/_/id”. The special field names “id”, “type”, “aclRead”, and “aclWrite” can be used to search for objects by id, type, and acl. The special sort field name “score” can be used to sort by score as determined by the indexing backend.
Fields under Cordra object “metadata”, “userMetadata”, and “acl” are also indexed and searchable, using fields which are “metadata”, “userMetadata”, or “acl” prepended to the JSON pointer within the metadata or userMetadata object. Examples include “metadata/createdOn”, “metadata/createdBy”, “metadata/modifiedOn”, “metadata/modifiedBy”, “acl/readers/_”, “acl/writers/_”.
See Query Syntax for more details and examples for the search API.
If the boolean parameters “ids” is set, for example as GET /search?query=…&ids, then the “results” will just be a list of ids rather than a list of Cordra objects.
Note: Former versions of Cordra would return all results with
pageSize=0. To restore this former behavior, you can add
"useLegacySearchPageSizeZeroReturnsAll":true to the Cordra design
object. By default a search with pageSize=0 returns the number of
matched objects but no object content.
Request:
GET /search?query=file&filter=["/id","/content/name"]
Response:
{
"size": 1,
"pageNum": 0,
"pageSize": -1,
"results": [
{
"id": "20.5000.1234/1321d2d033b22bee1187",
"content": {
"name": "A file"
}
}
]
}
Here the filter param is used to restrict the properties in the result objects. This may be desirable if your stored objects are large and your application only requires a part of each object.
The “facets” parameter to the search API allows faceted search, where the search results are augmented with a list of possible values that the field can take and a count of how many objects have each value.
The “facets” request parameter is a list of facet specifications, each of which has a “field” which is the index field (the JSON pointer) on which to perform faceting. A facet specification can also specify “maxBuckets”, the maximum number of buckets to return; this defaults to 10.
The “facets” property of search results is a list of facet results, each of which has the “field” and a list of “buckets”. Each “bucket” has a “value”, a “count” and a “filterQuery”. The “filterQuery” can be added verbatim to the “filterQueries” request parameter in order to restrict the search just to objects where the specified field has the specified value.
Request:
POST /search
Content-Type: application/json
{
"pageSize": 0,
"query": "+type:Document",
"facets": [
{
"field": "/author"
},
{
"field": "/status"
}
]
}
Response:
{
"size": 158,
"facets": [
{
"field": "/author",
"buckets": [
{
"value": "unknown",
"count": 148,
"filterQuery": "sort_/author:unknown"
},
{
"value": "John Doe",
"count": 10,
"filterQuery": "sort_/author:\"john doe\""
}
]
},
{
"field": "/status",
"buckets": [
{
"value": "release",
"count": 80,
"filterQuery": "sort_/status:release"
},
{
"value": "draft",
"count": 48,
"filterQuery": "sort_/status:draft"
},
...
]
}
]
}
Request:
DELETE /objects/<id>
Parameters |
||
|---|---|---|
id |
required |
The id of the object to delete. |
jsonPointer |
optional |
Indicates that instead of deleting the object, the object should be modified by deleting the content at the specified JSON pointer. |
Request:
DELETE /objects/20.5000.1234/23bdf2a62a83225a1b77
Response: empty
Request:
DELETE /objects/<id>?payload=<payload>
Parameters |
||
|---|---|---|
id |
required |
The id of the object containing the payload. |
payload |
required |
The name of the payload to delete. |
Request:
DELETE /objects/20.5000.1234/23bdf2a62a83225a1b77?payload=file
Response: empty
Request:
GET http://hdl.handle.net/20.5000.1234/23bdf2a62a83225a1b77?locatt=view:json
Parameters |
||
|---|---|---|
locatt |
optional, |
Used to specify if the redirect should respond with the json or the user interface. |
See Handle Integration for details about handle generation.
Request:
GET /acls/<id>
Parameters |
||
|---|---|---|
id |
required |
The id of the object to retrieve its acl. |
Request:
GET /acls/20.5000.1234/37b4ac94ba3e14665e04
Response:
{
"readers": [
"20.5000.1234/73675debcd8a436be48e"
],
"writers": [
"20.5000.1234/73675debcd8a436be48e"
]
}
Request:
PUT /acls/<id>
Parameters |
||
|---|---|---|
id |
required |
The id of the object you want to set permissions on. |
Request:
PUT /acls/20.5000.1234/37b4ac94ba3e14665e04
PUT Data:
{
"readers": [
"20.5000.1234/73675debcd8a436be48e"
],
"writers": [
"20.5000.1234/73675debcd8a436be48e"
]
}
The PUT data contains two arrays, readers and writers. These arrays
should contain the ids of the users that are given the associated permission.
Note that if a user is granted write permission this implicitly grants
them read permission.
The standard PUT /objects update API can be used to modify ACL values as well,
by including a part named “acl” in a multipart request.
NOTE: The ACL API has changed in Cordra 2.0. In version 1.0, the data arrays
were called read and write.
Response:
{
"readers": [
"20.5000.1234/73675debcd8a436be48e"
],
"writers": [
"20.5000.1234/73675debcd8a436be48e"
]
}
Request:
PUT /users/this/password
Request Headers |
|
|---|---|
Authorization |
Should be a Basic auth header or Bearer auth header with a JWT |
Changing a password requires using the Authorization header directly authenticating the user, instead of an access token. The body of the request should just be the new password.
Request:
PUT /users/this/password
PUT Data:
newPassword
Response:
{
"success": true
}
Request:
POST /check-credentials
Request Headers |
|
|---|---|
Authorization |
Should be a Basic or Bearer auth header. Optional. |
This call can be used to get information about the provided credentials. It can be used to check credentials for the given Authorization header, either for a direct authentication or for an access token. (It can also be used with the Legacy Sessions API to check credentials of a cookie-based session.)
Request:
GET /check-credentials
Parameters |
||
|---|---|---|
full |
optional |
If |
Response Attribute Name |
Description |
|---|---|
active |
Whether or not the authentication was successful. |
username |
Username of the authenticated user |
userId |
UserId of the authenticated user |
typesPermittedToCreate |
List of types this user can create; included when |
groupIds |
List of groups this user is in; included when |
See Type Methods for details about the server-side implementation of type methods.
Request:
POST /call?objectId=<objectId>&method=<method>&attributes=<attributes>
POST /call?type=<type>&method=<method>&attributes=<attributes>
Some Type methods may allow the use of GET rather than POST.
Parameters |
||
|---|---|---|
objectId |
optional |
The id of the object on which to call an instance method. Either objectId or type is required. |
type |
optional |
The type on which to call a static method. |
method |
required |
The name of the method to call. |
attributes |
optional |
A JSON object, possibly including a filename, a media type, and a request context. The attributes and filename, media type, and request context are made available to schema methods. |
The POST body is parsed as JSON and passed to the method as context.params.
Alternately the method can use context.directIo to access potentially non-JSON input (see Direct I/O).
If the method is accessed via GET (or POST with empty body) the input can be given by the URI query parameter “params”.
Call requests allow a query parameter called attributes. This must be a valid JSON object (suitably encoded as a query parameter).
For convenience, attributes as a JSON object can be
expressed as multiple properties in the API request with dot separated names.
If the value of some attributes.prop is valid JSON, then it is parsed as JSON.
Otherwise, the value is interpreted as a string. For example,
GET /call?...&attributes={"query":"foo","pageSize":10}
is exactly the same as
GET /call?...&attributes.query=foo&attributes.pageSize=10
By default this API requires write permission on the object or schema. ACLs for calling methods can be configured as described in Authorization for Type Methods.
Request:
GET /listMethods/?objectId=<objectId>
GET /listMethods/?type=<type>
GET /listMethods/?type=<type>&static
Parameters |
||
|---|---|---|
objectId |
optional |
The id of the object you want to list methods of. Either objectId or type is required. |
type |
optional |
A Cordra type; depending on the static parameter, this will list static methods on that type, or instance methods on objects of the type. |
static |
optional |
If present, listing methods for a type will list static methods instead of instance methods. |
The HTTP response is a list of strings which are the available method names.
Request:
POST /batchUpload
POST /batchUpload?format=ndjson
POST /batchUpload?failFast=true
Parameters |
||
|---|---|---|
format |
optional |
Set to ndjson to indicate that the format of the request body is newline-delimited JSON objects. |
failFast |
optional |
If |
parallel |
optional |
If |
Request:
POST /batchUpload?format=ndjson
POST Data:
{"type":"Foo","content":{}}
{"id":"test/e4673f57012b544e72af", "type":"Foo","content":{}}
Response:
{
"success": true
}
The input may optionally include an id on each object, as shown in the first example. For each object in the request
Cordra will first try to create that object. If the create operation fails because an object with that id already exists
an update will be performed.
By default the input objects will be processed in parallel in a multi-threaded fashion. As such they may not be
processed in the order they are supplied in the input. If you need the input objects processed in order you can
specify the optional query param parallel=false. It would then be the responsibility of the caller to ensure
any dependencies are correctly ordered. For example if you are creating an object of type Foo and the Schema Foo does
not yet exist, include the Schema object in the request before any instances that use it.
An alternative approach is to send multiple batch requests to the server. For example a first batch might include all the Schema objects and once complete, a second batch could contain all the instances of those types. Here each individual batch could safely be processed in parallel.
There are three supported request input formats:
Newline-Delimited JSON:
{...}
{...}
{...}
Cordra Search Results:
{
"results": [
{
...
},
{
...
},
{
...
}
]
}
Cordra Object JSON Array:
[
{
...
},
{
...
},
{
...
}
]
By default the API expects either Cordra Object JSON Array or Cordra Search Results. You do not need to specify
which as Cordra will detect between those two formats automatically. If you supply Newline-Delimited JSON you
must include the ?format=ndjson query param with the request.
Payload data may be included directly in the JSON as base64 encoded strings using the property name
base64Payload. For example:
[
{
"id": "test/123"
"type": "Foo",
"content": {},
"payloads": [
{
"base64Payload": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdA==",
"name": "payload",
"filename": "Loremipsum.txt",
"mediaType": "text/plain",
"size": 55
}
]
}
]
It is not necessary to include the base64Payload when updating an object. If base64Payload is missing on an
update the stored payload will remain unchanged. However if you want to delete a payload during an update you can specify
the payload names to be deleted in a top level property payloadsToDelete as shown below:
[
{
"id": "test/123"
"type": "Foo",
"content": {},
"payloadsToDelete": [
"loremipsum"
]
}
]
Warning
The following API was introduced in Cordra v2.0.0. If you are using an earlier version, please refer to Legacy Sessions API for information on using cookie-based sessions with the HTTP REST API.
The access token API can be used to authenticate only once to obtain an access token, which can then be provided for multiple calls. This way, the server does not need to reprocess your authentication credentials with each request, which can significantly speed up the process of making multiple requests.
Once authenticated using the access token API, the access token should be sent to other APIs using an Authorization Bearer header. For example:
Authorization: Bearer ACCESS_TOKEN
Request:
POST /auth/token
POST Data:
{
"grant_type": "password",
"username": <username_or_userid>,
"password": <password>,
}
or
{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": <JWT_for_keypair_authentication>
}
The POST data specifies whether the user is authenticating via username/password or via keypair, depending on the grant_type. If the grant_type is password, the POST data should contain the username (or user object id) and password. See Authentication via Keys for the details of the JWT assertion that must be included with keypair authentication.
Note that with some tools you must specify a header ‘Content-Type: application/json’ in order to have the POST body correctly interpreted as JSON.
Password authentication allows specifying either a username, or the Cordra object id of the user object. (If the two possible interpretations indicate two different Cordra objects, the Cordra object id will be used.)
Parameters |
||
|---|---|---|
full |
optional |
If |
Response Attribute Name |
Description |
|---|---|
access_token |
The newly created access token. |
token_type |
Always “Bearer”. |
active |
Whether or not the token is active; always “true” for successful calls of the /auth/token API. |
username |
Username of the authenticated user |
userId |
UserId of the authenticated user |
typesPermittedToCreate |
List of types this user can create; included when |
groupIds |
List of groups this user is in; included when |
Request:
POST /auth/introspect
{
"token": <token>
}
Parameters |
||
|---|---|---|
full |
optional |
If |
Response Attribute Name |
Description |
|---|---|
active |
Whether or not the token is active. |
username |
Username of the authenticated user |
userId |
UserId of the authenticated user |
typesPermittedToCreate |
List of types this user can create; included when |
groupIds |
List of groups this user is in; included when |
Request Headers |
|
|---|---|
Authorization |
Bearer <token> |
Request:
POST /auth/revoke
{
"token": <token>
}
Response:
{
"active": false
}
Resource |
Description |
|---|---|
GET /schemas/<type> |
Get schema or all schemas. |
PUT /schemas/<type> |
Create or update a schema. |
DELETE /schemas/<type> |
Delete a schema. |
POST /uploadObjects |
Bulk upload of objects from a json file. |
PUT /adminPassword |
Change the password for the admin user. |
POST /updateHandles |
Update all handle records for objects in Cordra. |
GET /updateHandles |
Get status of handle update. |
POST /reindexBatch |
Reindex all specified objects. |
GET /startupStatus |
Accessible even after failed startup to indicate success or failure. |
Request:
GET /schemas
GET /schemas/<type>
Request:
GET /schemas/JavaScriptDirectory
Response:
{
"type": "object",
"required": [
"directory"
],
"properties": {
"id": {
"type": "string",
"cordra": {
"type": {
"autoGeneratedField": "handle"
}
}
},
"directory": {
"type": "string",
"title": "Directory",
"cordra": {
"referrable": {
"id": true,
"payloads": "scripts"
}
}
}
}
}
Request:
PUT /schemas/<type>
Request:
PUT /schemas/JavaScriptDirectory
Request Body:
{
"type": "object",
"required": [
"directory"
],
"properties": {
"id": {
"type": "string",
"cordra": {
"type": {
"autoGeneratedField": "handle"
}
}
},
"directory": {
"type": "string",
"title": "Directory Changed",
"cordra": {
"referrable": {
"id": true,
"payloads": "scripts"
}
}
}
}
}
Response:
{
"msg": "success"
}
Request:
DELETE /schemas/<type>
Request:
DELETE /schemas/JavaScriptDirectory
Response:
{
"msg": "success"
}
Request:
POST /uploadObjects
Parameters |
||
|---|---|---|
deleteCurrentObjects |
boolean |
If true, delete all existing objects before uploading new objects. Otherwise, update objects. Default: false |
Request:
POST /uploadObjects
Request Body:
{
"results": [
{
"id": "test/171a0606f7c74580fd39",
"type": "Schema",
"content": {
"identifier": "test/171a0606f7c74580fd39",
"name": "Group",
"schema": < Schema json omitted for brevity >,
"javascript": < JavaScript omitted for brevity >
},
"metadata": {
"createdOn": 1535479938849,
"createdBy": "admin",
"modifiedOn": 1535479938855,
"modifiedBy": "admin",
"txnId": 65
}
},
{
"id": "test/171a0606f7c74580fd39",
"type": "Schema",
"content": {
"identifier": "test/171a0606f7c74580fd39",
"name": "Document",
"schema": < Schema json omitted for brevity >
},
"metadata": {
"createdOn": 1535479938849,
"createdBy": "admin",
"modifiedOn": 1535479938855,
"modifiedBy": "admin",
"txnId": 65
}
},
]
}
Response:
{
"msg": "success"
}
Used to update the admin user password.
Request:
PUT /adminPassword
Request Body:
{
"password": "newPassword"
}
Response:
{
"success": "true"
}
Used to update the admin user password.
Request:
POST /updateHandles
Response:
{}
Request:
GET /updateHandles
Response:
{
"inProgress": true,
"total": 123,
"progress": 52,
"startTime": 1535479938855,
"exceptionCount": 0
}
Used to reindex the specified list of objects. Takes a JSON array of object ids to be reindexed. When using object locking, which is on by default, batch sizes should be small e.g. 16. However many reindex requests can be sent in parallel.
An optional “query” query param can be sent instead of a list of ids in the body. The query will be executed and the results will be reindexed. The results will be reindexed by a single thread in batches of size 16.
Request:
POST /reindexBatch
Parameters |
||
|---|---|---|
lockObjects |
optional |
Defaults to ‘true’. Locks on object ids while objects are reindexed. You should only set this to ‘false’ if users are not using the system during reindexing, or it is otherwise possible to guarantee that the objects being reindexed will not be concurrently updated. If this is possible, performance is improved by setting this to false. |
query |
optional |
A lucene query that can be sent instead of a list of ids in the body. |
all |
optional |
If set, all objects will be reindexed from storage. |
Request Body:
[
"test/abc",
"test/def",
"test/xyz"
]
Response:
{
"success": "true"
}
This API provides some information about how far startup progressed, even in the event of startup failure. This is useful in installations where remote access is easier than directly looking at log files; however, the amount of information provided is very limited. It will contain a “state” which is either “UP” or “FAILED”, and a “details” which will contain the status (“UP” or “FAILED”) of some of the following, depending on your Cordra configuration:
“storage”: Cordra’s configured storage module
“indexer”: Cordra’s configured indexer module
“zookeeper”: subsystem for accessing ZooKeeper (for a distributed Cordra)
“replicationProducer”: subsystem for sending transactions to be replicated (using Kafka)
“replicationConsumer”: subsystem for receiving transactions to be replicated (using Kafka)
If the “state” is “FAILED”, this request will return an HTTP 500 response for ease of monitoring.
Request:
GET /startupStatus
Response:
{
"state": "UP",
"details": {
"storage": "UP",
"indexer": "UP"
}
}
Resource |
Description |
|---|---|
GET /versions/?objectId=<objectId> |
Get version information for a specific object. |
POST /versions/?objectId=<objectId> |
Create a version of a specific object. |
Request:
GET /versions/?objectId=<objectId>
Parameters |
||
|---|---|---|
objectId |
required |
The id of the object you want version information on. |
Request:
GET /versions/?objectId=20.5000.1234/eb3b797f9fd544fb90fb
Response:
[
{
"id": "20.5000.1234/208b07aec73a36b91a1b",
"type": "Foo",
"versionOf": "20.5000.1234/eb3b797f9fd544fb90fb",
"publishedBy": "admin",
"publishedOn": 1436380157539,
"isTip": false
},
{
"id": "20.5000.1234/eb3b797f9fd544fb90fb",
"type": "Foo",
"modifiedOn": 1433957772377,
"isTip": true
}
]
Request:
POST /versions/?objectId=<objectId>
Parameters |
||
|---|---|---|
objectId |
required |
The id of the object you want to create a version of. |
versionId |
optional |
The desired id of the new version. If omitted Cordra will mint an id. |
clonePayloads |
optional |
If present, the new version object will not contain a copy of the payloads. |
Request:
POST /versions/?objectId=20.5000.1234/eb3b797f9fd544fb90fb
Response:
{
"id": "20.5000.1234/37b4ac94ba3e14665e04",
"type": "Foo",
"versionOf": "20.5000.1234/eb3b797f9fd544fb90fb",
"publishedBy": "admin",
"publishedOn": 1436380685442,
"isTip": false
}