REST API Overview

All API requests are made under the /api/v1/ path of the Colectica Repository web site. Requests and responses use JSON, except for the DDI XML endpoints. Item types, formats, and relationship predicates are identified by the UUIDs listed in Item Type Identifiers.

Each endpoint requires the caller to hold one of the Colectica roles. The roles required for every endpoint are listed in REST API Endpoints and Roles.

Repository Information

• GET /api/v1/repository/info - Retrieve a RepositoryInfo object containing the repository’s title, the agencies for which it is authoritative, and the permissions of the current user.

• GET /api/v1/repository/statistics - Retrieve summary statistics about the types, counts, and revisions of items currently registered.

Managing Registration Authorities

The repository must be configured with the Registration Authority names, usually DDI agency identifiers, for which it is authoritative.

• POST /api/v1/agency - Registers an identifier for a Registration Authority with the repository.

• DELETE /api/v1/agency/{agency} - Removes a Registration Authority from a repository. This does not remove any Administered Items; it only changes the repository’s state to Non-Authoritative for that agency.

Registering Items

Administered items can be registered by authorized clients.

• POST /api/v1/item - Register one or more administered items with the repository. The response lists any conflicts.

Items are submitted by sending the DDI serialization of each item along with the item’s ISO 11179 IRDI, composed of the agency, identifier, and version. An item type, item format, and commit options are also included to control the repository’s registration behavior. It is at this stage that an item may be deserialized from XML for further processing and indexing.

Transactions

Large or related sets of items can be registered within a transaction, so that they become visible together.

• POST /api/v1/transaction - Create a transaction.

• POST /api/v1/transaction/_addItemsToTransaction - Add items to an open transaction.

• POST /api/v1/transaction/_commitTransaction - Commit a transaction. Commit options control how versions are assigned and propagated to parent items.

• POST /api/v1/transaction/_cancelTransaction - Cancel a transaction.

• POST /api/v1/transaction/_getTransactions, POST /api/v1/transaction/_listTransactions, POST /api/v1/transaction/_getItemsInTransaction - Inspect transactions and their items.

Retrieving Items

There are many ways to retrieve administered items stored in the repository.

• GET /api/v1/item/{agency}/{id}/{version} - takes an ISO 11179 international registration data identifier (IRDI) and returns a RepositoryItem object containing information about an Administered Item and its XML serialization.

• GET /api/v1/item/{agency}/{id} - takes only the agency and identifier, and returns a RepositoryItem object containing the latest revision of an administered item.

• POST /api/v1/item/_getList and POST /api/v1/item/_getListLatest - These calls take a collection of IRDIs or agency and identifier pairs, and are for performance improvement. They can be used to substitute successive calls to their single item counterparts.

• POST /api/v1/item/_exists - Check which of a collection of IRDIs exist in the repository.

All of these methods return an object called a RepositoryItem. It contains not only the XML serialization of the administered item, but also additional repository metadata about it including a collection of standardized notes, item type, version date, version author, version rationale, published status, deprecated status, and repository authority information.

DDI and JSON Documents

For clients that need the DDI XML or a JSON representation of an item without the repository wrapper:

• GET /api/v1/ddi/{agency}/{identifier}/{version} - The DDI Lifecycle fragment for an item.

• GET /api/v1/ddiset/{agency}/{identifier}/{version} - A DDI Lifecycle fragment instance containing the item and every item it references, directly or indirectly.

• GET /api/v1/json/{agency}/{identifier}/{version} - A JSON representation of the item.

• GET /api/v1/jsonset/{agency}/{identifier}/{version} - A nested JSON representation of the item and its set.

• POST /api/v1/jsonset/filtered - A nested JSON set, limited to accepted item types.

The version may be omitted from these URLs to retrieve the latest version.

Retrieving Item Metadata

When only the administered item’s title or description is needed by a client, this series of calls can be used to increase performance.

• GET /api/v1/item/{agency}/{id}/{version}/description and POST /api/v1/item/_getDescriptions - These calls take a single or collection of IRDIs to retrieve a RepositoryItemMetadata object. It contains the identity information of the administered item and multilingual fields for ItemName, Label, Description, and Summary texts.

• POST /api/v1/_query/relationship/bysubject/descriptions and POST /api/v1/_query/relationship/byobject/descriptions - These are analogous to the relationship search, taking a GraphSearchFacet object as a parameter. They differ in that they return a collection of RepositoryItemMetadata objects instead of identifiers.

Set Management

Sets, similar to the RDF concept of a named graph, allow for the discovery of working sets.

• GET /api/v1/set/{agency}/{id}/{version} - takes an IRDI that specifies the root item in the set and returns a list of IRDIs of items present.

• GET /api/v1/set/{agency}/{id}/{version}/typed - returns the same list along with the item type of each item.

• GET /api/v1/set/{agency}/{id} - This special case uses the latest version of any referenced administrative item in the object graph, and follows the latest item’s references when determining set boundaries.

• POST /api/v1/_query/set - Search for items of certain types within a set.

Versioning

The Colectica Repository provides full support for item versioning.

• GET /api/v1/item/{agency}/{id}/versions/_latest - find the latest version number in the repository

• GET /api/v1/item/{agency}/{id}/{tag}/versions/_latest - find the latest version number with a given tag

• POST /api/v1/item/_getLatestVersionNumbers - find the latest version numbers for a set of administered items. This is for increased performance for multiple calls.

• GET /api/v1/item/{agency}/{id}/versions - retrieve a list of all IRDIs corresponding to the agency and identifier of an administered item

• GET /api/v1/item/{agency}/{id}/history - retrieve all RepositoryItemMetadata stored by the repository for all revisions of an item.

Every revision of an item registered to the repository is saved, allowing clients to retrieve a full version history of any item in the repository. Each revision includes additional information in the RepositoryItemMetadata object:

• the authenticated user who committed the version

• the date and time the version was committed

• an optional message describing the reason for the version

• additional publication, rights, and deprecation information

Deprecating and Deleting Items

In order to provide complete audit functionality, repository items are normally not deleted. If an item is no longer needed it may be deprecated. Search requests can indicate whether they wish to include deprecated items in the results. Items can also be restored, or marked as no longer being deprecated.

• POST /api/v1/item/_updateState - marks items as deprecated, or restores them.

Administrators can permanently delete items when the RepositorySettings:Features:EnableItemDeletion setting is enabled.

• POST /api/v1/item/_delete - deletes items, item sets, or the items in a transaction.

Search

The Colectica Repository offers advanced faceted search functionality.

• POST /api/v1/_query - The search method takes a collection of facets and search options, returning a search response.

• POST /api/v1/_query/advanced - Fine-grained search over indexed text, code value, numeric, date, and boolean properties. See Advanced Search.

• POST /api/v1/_query/relationship/bysubject - Request all relationships that the subject IRDI participates in with the given predicate. This includes relations to other IRDIs and is determined based on child objects and references.

• POST /api/v1/_query/relationship/byobject - Request all relationships that contain the specified IRDI as the object of a statement based on the given predicate. This can be used to determine parent objects and locations that have references to the specified IRDI.

• POST /api/v1/_query/relationship/matrix and POST /api/v1/_query/relationship/matrix/typed - Request the relationships among a collection of items.

Facets

A query may consist of the following facets:

• Item type

• Item text

• Location of item text (e.g., choose to find text in an item’s name or label)

• Language of item text

• Agency identifier

• Sets of items to search within

• Relationships to other items (using supplemental method calls)

Options

A search may also specify the following options:

• Maximum number of results to return

• Whether results should be paged

• Whether to rank the results

• Whether to return only the latest version of matching items, or all matching versions

• Whether to search deprecated items

• Whether to perform full-text search by prefix

Search Response

The Colectica Repository returns results of matching items with the following information:

• Type of object

• Unique identifier

• Agency identifier

• Version number

• Summary text describing the matching item

• Hostname of the authoritative repository

• Whether the queried repository is authoritative

• Whether the item is deprecated

• A composite identifier (IRDI) consisting of the authoritative agency identifier, the item’s unique identifier, and the item’s version number

Tagging

A specific version of any item may be tagged. A tag is simply a name given to the version so it can be easily referenced in the future. Tagging can be used to mark milestones such as publication.

• PUT /api/v1/item/{agency}/{id}/{version}/tag/{tag} - create a tag for an administered item

• GET /api/v1/item/{agency}/{id}/{version}/tag - get a listing of tags for an administered item

• DELETE /api/v1/item/{agency}/{id}/{version}/tag/{tag} - remove a tag

Repository Item Annotations

Users with the appropriate role may annotate items stored in the Colectica Repository in a number of ways.

• POST /api/v1/item/{agency}/{id}/{version}/comment - An authenticated user may make a comment on any Administered Item in the repository. This will also include the user’s name and date information.

• GET /api/v1/item/{agency}/{id}/comment and POST /api/v1/item/_getCommentList - Get all comments about Administered Items, and which revision they were applied to.

• POST /api/v1/item/{agency}/{id}/{version}/rating - Allows a user to rate an Administered Item for quality

• GET /api/v1/item/{agency}/{id}/{version}/rating - Get all ratings about an Administered Item.

Note

Implementers Note: User annotations are displayed on item pages in Colectica Portal when commenting and rating are enabled by the administrator.

Permissions

• POST /api/v1/permission - Add item or item type permissions.

• POST /api/v1/permission/_get - Retrieve permissions.

• POST /api/v1/permission/_delete - Remove permissions.

See Permission Management.

Repository Settings

Administrators can read and write the repository’s named settings.

• GET /api/v1/setting and GET /api/v1/setting/{setting} - Retrieve settings.

• POST /api/v1/setting - Create or update a setting.

• DELETE /api/v1/setting/{setting} - Remove a setting.

Events

• POST /api/v1/event - Record an event from a client application in the repository’s log.

Workflow Replication

When Colectica Workflow Services is configured, the /api/v1/replication endpoints allow clients such as Colectica Designer to list replication targets, request the replication of an item set to another repository, and change the state of a replication request. See Colectica Workflow Services.

Error Responses

Errors are returned as JSON problem details with an HTTP status code. Repository error codes are mapped to status codes as follows.

HTTP status	Meaning
400 Bad Request	The request or item content is not valid (R0003, R0004, R0010, R0014, R0017, R0020).
401 Unauthorized	The caller is not authenticated, or does not hold a required role.
403 Forbidden	The operation is disabled, such as deletion (R0025).
404 Not Found	The item, version, or setting does not exist (R0009, R0011, R0013, R0018, R0019), or the API is not enabled.
409 Conflict	A newer version of the item already exists (R0005, R0012).
503 Service Unavailable	The database is unavailable (R0001, R0002), or advanced search is not enabled.