{"type":"doc","content":[{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Table of Contents","type":"text","marks":[{"type":"strong"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"2"},"maxLevel":{"value":"2"},"outline":{"value":"false"},"style":{"value":"disc"},"type":{"value":"list"},"printable":{"value":"true"}},"macroMetadata":{"macroId":{"value":"61238332-bf9b-4488-b70b-6e3bac86513a"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"c4d3f7d6-82a9-4778-af33-6fd7dc6cffa8"}}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"About CollectionSpace REST-based API","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"All of CollectionSpace's exposed services offer a REST-based Application Programming Interface (API). This API allows you to perform CRUD+L operations (create, read, update, and delete of individual resources, plus list operations such as list all, keyword search, and partial term matching) on a variety of entities that represent a museum's or related institution's collections, such as collection objects, acquisitions, and loans. You can also use this same API to manage a number of the internal entities within a CollectionSpace system, such as user accounts.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are some minor variations in this API from service to service. However, nearly all services accept requests and provide responses in nearly exactly the same way. The API functionality that is common across all the services is documented here. For details of the REST APIs for individual services, please see ","type":"text"},{"text":"Services Layer REST API","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://collectionspace.atlassian.net/wiki/spaces/CSPACE50/pages/665882906"}}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"general principles","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://collectionspace.atlassian.net/wiki/spaces/CTDN/pages/3577544705"}}]},{"text":" of this API are described first, followed by the common features of the ","type":"text"},{"text":"CRUD+L operations","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://collectionspace.atlassian.net/wiki/spaces/CTDN/pages/3576922154"}}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"General principles","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Item-level CRUD and List operations","type":"text"}]},{"type":"paragraph","content":[{"text":"Most services support both item-level CRUD operations and List operations (hence \"CRUD+L\"):","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The item-level CRUD operations allow you to create, read, update and delete individual resources. Most services use a uniform schema to describe these resources, which is used in both create and update requests, and in the responses returned from read requests. This schema is divided into several parts, following the principles articulated in the CollectionSpace Services Architecture. A small number of services return a schema consisting only of a single part.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The list operations return lists of multiple resources. The list operations of most services use a second, uniform schema, which returns minimal, summary information about each item, together with identifiers that can be used to individually retrieve more detailed information about any item. The type of data returned for each item is generally independent of the type of list function (e.g. list all, query, term suggestion) for a given service. There are plans to support mechanisms to request that additional fields be added to the returned results, but this functionality is not yet supported. Most services support pagination of list results. See details below, and in individual service API documentation.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Invoking the REST APIs","type":"text"}]},{"type":"paragraph","content":[{"text":"All services are invoked with HTTP requests:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HTTP POST requests are used to create resources.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HTTP GET requests are used to read resources. They are also used in list operations that may return multiple items, such as list all, keyword search and partial term matching (term suggestion / term completion).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HTTP PUT requests are used to update (change) resources.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HTTP DELETE requests are used to delete resources.","type":"text"}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Payloads","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Payloads - data that you will send in some of your requests to the services, and that you will receive in some of your responses from the services - share some common characteristics:","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Payloads for individual records","type":"text"}]},{"type":"paragraph","content":[{"text":"Payloads for individual records in ","type":"text"},{"text":"most","type":"text","marks":[{"type":"em"}]},{"text":" CollectionSpace services are extensible. Extensibility is provided by bundling multiple parts for each record in Create, Read and Update operations: a \"core\" part, a \"common\" part, and zero or more ","type":"text"},{"text":"optional","type":"text","marks":[{"type":"em"}]},{"text":" extension parts. Details regarding this:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"With each service that supports extensible schema, the payloads you will send and receive for ","type":"text"},{"text":"individual resources","type":"text","marks":[{"type":"em"}]},{"text":", in Create, Read and Update operations, are XML documents, with a Content-Type header of ","type":"text"},{"text":"application/xml","type":"text","marks":[{"type":"em"}]},{"text":". (Note that Delete operations don't exchange a payload in the body of the request.) Each field in an object or procedural record is usually represented by a corresponding element in that XML document.","type":"text"}]},{"type":"paragraph","content":[{"text":"Payloads consist of one or more parts, each contained within separate XML elements:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each part is associated with one of the layered schemas, as described in the Schema Extension documentation:","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There will be:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One core part. This part contains metadata about the record, such as when, and by whom, it was created and last modified. Fields in this part are set internally when a record is created, and the updatedAt and updatedBy fields are refreshed each time the record is updated. The core part is read-only; if an incoming payload includes this part, its values will be ignored.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One common part. This part contains the set of standard (or \"common\") fields for the CollectionSpace record of that type (e.g. CollectionObjects, Acquisitions, LoansOut ...)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Zero or more ","type":"text"},{"text":"optional","type":"text","marks":[{"type":"em"}]},{"text":" extension parts. Each extension part, if any, will contain a set of new fields that extend the standard CollectionSpace record type. Extension parts may in turn be associated with a \"domain\" (containing fields defined by a community of museums or a similar body, and often associated with a specific discipline such as fine arts, anthropology, or botany) or be a \"local\" part (containing fields unique to your own museum).","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Some response payloads may also return an additional part or parts, such as a part containing information about related resources.","type":"text"}]}]}]}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Suggested addition","type":"text"}]},{"type":"paragraph","content":[{"text":"Add: \"Payload parts are denoted by the prefix 'ns2:' (for example, )\"? Is this prefix used consistently throughout the service payloads?","type":"text"}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"With each service that does not support extensible schema, or where the request or response contains the payload only from a single schema, the payloads that you will send and receive for individual resources, in Create, Read and Update operations, will typically be an XML document, with a Content-type header of ","type":"text"},{"text":"application/xml","type":"text","marks":[{"type":"em"}]},{"text":". Each field in an object or procedural record is usually represented by a corresponding element in that XML document.","type":"text"}]},{"type":"paragraph","content":[{"text":"Some notable examples of services that do not support extensible schema are the Account service, Authorization service, and the ID service. List operations also follow this model (see below).","type":"text"}]},{"type":"paragraph","content":[{"text":"(In the case of just the ID service, payloads of ","type":"text"},{"text":"text/plain","type":"text","marks":[{"type":"em"}]},{"text":" are currently returned by one Read operation: that of retrieving new IDs. This may later change to an XML-based payload, for uniformity with other services.)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Payloads for lists","type":"text"}]},{"type":"paragraph","content":[{"text":"When you directly request a ","type":"text"},{"text":"list of resources","type":"text","marks":[{"type":"em"}]},{"text":", or when a list of resources is returned in response to a search, partial term match, request for related authorities, or similar operations, the payload you will receive will be an XML document, with a Content-type header of ","type":"text"},{"text":"application/xml","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Each item in the list will be contained within an 'item'-type element, whose name will vary. ","type":"text"}]},{"type":"paragraph","content":[{"text":" Each item in a list contains compact, summary information for each resource. This summary information will typically contain one or two displayable fields, as well as the identifier and URL for retrieving the full record for that item. ","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":4},"content":[{"text":"Sparse payloads","type":"text"}]},{"type":"paragraph","content":[{"text":"The services support \"sparse\" payloads, which contain only a subset of the fields listed in the schema for a record type.","type":"text"}]},{"type":"paragraph","content":[{"text":"When creating or updating an individual record (or resource), any fields not passed in the payload will not be affected:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"On create, missing/unspecified values will take default values - usually null.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"On update, missing/unspecified values will not be changed (except subject to validation rules).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When reading a record (or resource), only fields that have non-null values - populated by a prior create or update, or by a service itself - will be returned. Fields containing null values will not be returned.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Repeatable fields and field groups","type":"text"}]},{"type":"paragraph","content":[{"text":"The services support repeatable (also known variously as multivalued, multivalue, or repeating) fields and field groups.","type":"text"}]},{"type":"paragraph","content":[{"text":"For some record types, it is specified that:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Certain fields can optionally be repeated (that is, occur more than once).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Certain groups of fields can optionally be repeated.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Within a group of fields that can be repeated, certain fields in that group can themselves optionally be repeated.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Entire Information Groups can be repeated.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A repeatable field is represented in payloads in the form of a parent field, which acts solely as a container, and zero or more instances of a repeatable child field. Example:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"071cbefb-5240-4aa0-8f74-934a308cb6d7"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" urn:cspace:org.collectionspace.demo:personauthority:id(TestPersonAuthority):item:name(SallyKRide)'Sally K. Ride'","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" urn:cspace:org.collectionspace.demo:personauthority:id(TestPersonAuthority):item:name(RobertLCrippen)'Robert L. Crippen'","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ...","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"As shown in the example above, it is permissible to create or update an instance of a repeatable field with a value that is empty (blank).","type":"text"}]},{"type":"paragraph","content":[{"text":"Tenant name in URN; other changes?","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that the urn now includes a segment that indicates the tenant, as in this example:","type":"text"}]},{"type":"paragraph","content":[{"text":"urn:cspace:","type":"text"},{"text":"core.collectionspace.org","type":"text","marks":[{"type":"link","attrs":{"href":"http://core.collectionspace.org/"}}]},{"text":":vocabularies:name(conditionfitness):item:name(unsuitable)'Unsuitable'","type":"text"}]},{"type":"paragraph","content":[{"text":"('core' is the tenant in this example.)","type":"text"}]},{"type":"paragraph","content":[{"text":"Has anything else changed?","type":"text"}]},{"type":"paragraph","content":[{"text":"A repeatable group of fields is represented in payloads in the form of a grandparent \"list\" field, which acts solely as a container; a parent \"group\" field, which also acts solely as a container, and zero or more instances of the fields within that group. Example (to show structure only; this is not an example from any CollectionSpace record type):","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"99d43103-9200-45fd-9c39-873d6a1b6caf"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" value","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" value","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" value","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" value","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" value","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":" ...","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"Authentication is required to call CollectionSpace REST services. CollectionSpace REST services use ","type":"text"},{"text":"HTTP Basic Authentication","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.w3.org/Protocols/HTTP/1.0/draft-ietf-http-spec.html#BasicAA"}}]},{"text":" with HTTPS ","type":"text"},{"text":"server side authentication","type":"text","marks":[{"type":"link","attrs":{"href":"http://en.wikipedia.org/wiki/Transport_Layer_Security#Simple_TLS_handshake"}}]},{"text":". An authentication token for the end user must be provided in the HTTP header.","type":"text"}]},{"type":"paragraph","content":[{"text":"The HTTP error code 401 (Unauthorized) with response message is used by the CollectionSpace services to challenge the authorization of a user agent. Upon receipt of an unauthorized request for a URI within the CollectionSpace protection space, the server will respond with a challenge like the following:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"8c03a36b-c4aa-4755-a4a6-0896f1894da2"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"WWW-Authenticate: Basic realm=\"org.collectionspace.services\"","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"In response, the user agent could send an authentication token, consisting of the userid and password Base64 encoded as follows:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"a7543b60-2e73-4891-a85b-350b2564ba7b"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Where QWxhZGRpbjpvcGVuIHNlc2FtZQ== is an example of ","type":"text"},{"text":"userid:password","type":"text","marks":[{"type":"code"}]},{"text":" in Base64 encoded form. Note that in the authentication token, the userid and password are delimited (separated) by a colon character (","type":"text"},{"text":":","type":"text","marks":[{"type":"code"}]},{"text":"), prior to being Base64 encoded. Refer to ","type":"text"},{"text":"HTTP Basic Authentication","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.w3.org/Protocols/HTTP/1.0/draft-ietf-http-spec.html#BasicAA"}}]},{"text":" for more details.","type":"text"}]},{"type":"paragraph","content":[{"text":"In a future release of the CollectionSpace system, the calling application may also be required to provide an authorized application ID.","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"List results, filtering, pagination controls, sorting and search","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"List results","type":"text"}]},{"type":"paragraph","content":[{"text":"All REST services allow you to obtain lists of items. Each item in a list contains compact, summary information for each resource. This summary information will typically contain one or two displayable fields, as well as the identifier and URL for retrieving the full record for that item.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the future, it may be possible to configure and/or more flexibly specify the fields returned in summary information, for export and other purposes.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"List pagination","type":"text"}]},{"type":"paragraph","content":[{"text":"Most REST services that provide lists of results also support pagination of the results. Rather than receiving many thousands of records upon a GET request for, say, cataloging records, you can instead request a single \"page\" of the list, containing a smaller subset of those records, and then you can 'page through' the entire list.","type":"text"}]},{"type":"paragraph","content":[{"text":"You can control how many records are returned per page, and which page of records to retrieve, by adding query parameters onto your GET request:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pgSz","type":"text","marks":[{"type":"strong"}]},{"text":" indicates the number of results to return per page.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"pgSz","type":"text","marks":[{"type":"code"}]},{"text":" is not provided, the default behavior will return 40 items on each page of the list results (with the potential ability in the future to be able to configure this centrally and/or per service).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pgSz","type":"text","marks":[{"type":"code"}]},{"text":" has a maximum value of 1000 (should probably support configuration of this as well).","type":"text"}]},{"type":"paragraph","content":[{"text":"This maximum needs to be verified. I could not find a maximum constant or configured value, and was able to retrieve 2000 person items on Nightly by setting ","type":"text"},{"text":"pgSz=2000","type":"text","marks":[{"type":"code"}]},{"text":", with a total dataset of 2064 such records. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Setting ","type":"text"},{"text":"pgSz=0","type":"text","marks":[{"type":"code"}]},{"text":" will return up to the maximum number of items, on a single page. (When large numbers of items will be returned, the response to a ","type":"text"},{"text":"pgSz=0","type":"text","marks":[{"type":"code"}]},{"text":" request may be somewhat slow.)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"pgNum","type":"text","marks":[{"type":"strong"}]},{"text":" indicates the page number to return. This leverages the ","type":"text"},{"text":"pgSz","type":"text","marks":[{"type":"code"}]},{"text":" value to produce the starting offset for the returned results.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"pgNum","type":"text","marks":[{"type":"code"}]},{"text":" is not provided, the default behavior will return the first page (page 0, as discussed below) of the list results.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pages are zero-based; you can request the first page of results via ","type":"text"},{"text":"pgNum=0","type":"text","marks":[{"type":"code"}]},{"text":", the second page via ","type":"text"},{"text":"pgNum=1","type":"text","marks":[{"type":"code"}]},{"text":", and so on.","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"The list schemas for these services include information about the pagination before the list items:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"element reflects the pgNum request made (0, by default)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"element reflects the pgSz request made, or the default page size.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"element reflects the total number of items in the current page.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"element reflects the total number of items found for the list or search query.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"element identifies the fields returned within each list item. The value of that element consists of a pipe-delimited (\"|\") list of field names.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Filtering on workflow state","type":"text"}]},{"type":"paragraph","content":[{"text":"Most REST services that provide lists of results support filtering on workflow state.","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, all records are returned in list results, regardless of workflow state. Optionally, you can specify that records matching a particular workflow state, or states, will be excluded from list results.","type":"text"}]},{"type":"paragraph","content":[{"text":"The sole workflow state on which you can currently filter records is the \"soft\" deleted state. A record that has been \"soft\" deleted has been marked for deletion, but the record and its data still exist.","type":"text"}]},{"type":"paragraph","content":[{"text":"To ","type":"text"},{"text":"exclude","type":"text","marks":[{"type":"em"}]},{"text":" records in the \"soft deleted\" state from list results, so that only active (non-deleted) records are returned, add the following query parameter to your GET request:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"25a5c252-8b76-4438-a8e2-52ee343b0858"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"?wf_deleted=false","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"(In addition, individual records in the \"soft deleted\" state can also be excluded from being returned from results. )","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Sorting","type":"text"}]},{"type":"paragraph","content":[{"text":"Most REST services that provide lists of results also support sorting of the results. You can specify the field on which to sort by adding query parameters onto your GET request:","type":"text"}]},{"type":"paragraph","content":[{"text":"sortBy","type":"text","marks":[{"type":"strong"}]},{"text":" indicates the field on which to sort. The value of this parameter takes a schema name, a colon (':') as a delimiter, and a field name within that schema, as defined by the services. Examples:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"ec44a898-616b-4680-a89f-5819cea12c4e"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"?sortBy=collectionobjects_common:distinguishingFeatures","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"39933464-ce68-470d-aaa1-d1ca290f4866"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"?sortBy=collectionobjects_local:myCustomField","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"The second example above sorts on a custom field, within a museum's local schema for a collection object - in this hypothetical example named \"collectionobjects_local\".","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, sorted results are returned in ascending order: from first to last. \"Empty\" (null or empty string) values are returned in sort order before non-empty values. To sort in descending order, add \"+DESC\" to the end of the field name. Example:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"f6ed50c3-0c07-4658-b684-1c0ef5789053"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"?sortBy=movements_common:locationDate+DESC","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"To sort on more than one field, separate each sort field with ","type":"text"},{"text":",+","type":"text","marks":[{"type":"code"}]},{"text":". Example:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"987557cc-5425-4ae8-86aa-8940e802c23d"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"?sortBy=movements_common:locationDate+DESC,+movements_common:movementNote","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Records will be ordered by the first sort field provided; then, ","type":"text"},{"text":"within that ordering","type":"text","marks":[{"type":"em"}]},{"text":", by the second sort field, and so on. In the example above, records will first be sorted by their location date fields in descending order; then, in cases where there are multiple records with identical location dates, they will be sorted by their movement note fields in ascending order.","type":"text"}]},{"type":"paragraph","content":[{"text":"In contrast with pagination details, details regarding the sort order used are not currently returned in the list results. These are scheduled to be added in a future release.","type":"text"}]},{"type":"paragraph","content":[{"text":"Records will be ordered by the collation (ordering) behavior of your database system. This may, in turn, be based on collation and language settings for your database, your operating system, or both. Collectively, these settings may determine whether (in the Roman alphabet, for instance) uppercase and lowercase characters (like \"A\" and \"a\") are ordered together or separately; how characters with diacritical marks are ordered, relative to similar characters without those marks; and how punctuation and other special characters are handled when ordering. By adjusting those settings, you may also be able to adjust how records in CollectionSpace are ordered, when you use the ","type":"text"},{"text":"?sortBy=","type":"text","marks":[{"type":"code"}]},{"text":" query parameter.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Search (query)","type":"text"}]},{"type":"paragraph","content":[{"text":"Some services support search (query) methods to return matching items, e.g., partial matches against a name, or matches against a keyword index. These return results as for the basic list operation, but filtered according to the query parameters. The query parameters are specific to each service, although certain patterns will be seen:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For those services that support keyword index search, the query parameter \"kw=","type":"text"},{"text":"term","type":"text","marks":[{"type":"em"}]},{"text":"\" specifies the ","type":"text"},{"text":"keyword","type":"text","marks":[{"type":"em"}]},{"text":" on which to search.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For those services (primarily Authorities and Vocabularies) that support partial term matching (aka term suggestion or term completion search), the query parameter \"pt=","type":"text"},{"text":"term","type":"text","marks":[{"type":"em"}]},{"text":"\" specifies the ","type":"text"},{"text":"partial term","type":"text","marks":[{"type":"em"}]},{"text":" to match.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For those services (primarily Authorities and Vocabularies) that support termStatus filtering (aka filtering results based upon termStatus values), the query parameter \"ts=","type":"text"},{"text":"term1","type":"text","marks":[{"type":"em"}]},{"text":"|","type":"text"},{"text":"term2","type":"text","marks":[{"type":"em"}]},{"text":"\" specifies the list of ","type":"text"},{"text":"term","type":"text","marks":[{"type":"em"}]},{"text":"s to match. Note that the separator ('|') is URL encoded as %7C.","type":"text"}]}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"There have been discussions about different ","type":"text"},{"text":"profiles","type":"text","marks":[{"type":"em"}]},{"text":"of information that would be defined (probably in configuration) and specified as query parameter to the List operation. In addition, we may support a facility to include extra, specific fields (from any of the common, domain, or local schema parts) for each instance in the list-results information returned. Once this functionality has been resolved, it will be documented here.","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Related records","type":"text"}]},{"type":"paragraph","content":[{"text":"In a CollectionSpace system, with only a few exceptions, any two records can be related to one another. Some representative examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Multiple Cataloging / CollectionObject records can be related to an Intake, Acquisition, Loan In, Loan Out, or Object Exit record.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Similarly, multiple Location/Movement/Inventory records can be related to a Cataloging / CollectionObject record.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Some records can also be hierarchically related to one another. Some representative examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Multiple Cataloging / CollectionObject records can be related in a hierarchy. Each record can optionally be related to one Broader Object (its immediate parent) and/or one or more Object Components (its immediate children).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Multiple authority term records can be related in a hierarchy. Each term can optionally be related to one Broader Context term (its immediate parent) and/or one or more Narrower Context terms (its immediate children).","type":"text"},{"type":"hardBreak"},{"text":"A sample three-level authority term hierarchy:","type":"text"}]},{"type":"paragraph","content":[{"text":"Broader Context","type":"text"}]},{"type":"paragraph","content":[{"text":"Term","type":"text"}]},{"type":"paragraph","content":[{"text":"Narrower Context","type":"text"}]},{"type":"paragraph","content":[{"text":"-","type":"text"}]},{"type":"paragraph","content":[{"text":"North America","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Canada","type":"text"}]},{"type":"paragraph","content":[{"text":"North America","type":"text"}]},{"type":"paragraph","content":[{"text":"Canada","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Ontario","type":"text"},{"type":"hardBreak"},{"text":"Quebec","type":"text"}]},{"type":"paragraph","content":[{"text":"Canada","type":"text"}]},{"type":"paragraph","content":[{"text":"Ontario","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"-","type":"text"}]},{"type":"paragraph","content":[{"text":"Canada","type":"text"}]},{"type":"paragraph","content":[{"text":"Quebec","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"-","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"There are three different categories of REST API calls to return related records. The calls in two of these categories each return lists of Relation records, the \"linking\" records that relate any two other types of records. Calls in the third category, in contrast, directly return lists of records of a particular type that are related to the specified record. ","type":"text"}]},{"type":"rule"}],"version":1}

Browser not supported