Web Services Overview

Managing Registration Authorities

The repository must be configured with the Registration Authority names for which it is authoritative. This is done through two web service calls.

• CreateRepository - Registers an identifier for a Registration Authority with the repository. This will usually be a DDI agency ID.

• RemoveRepository - 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 RAI.

Repository Information

A user of the Colectica Repository may obtain information about the repository.

• GetRepositoryInfo - Retrieve a RepositoryInfo object containing repository and user permissions

The repository information includes Dublin Core metadata about the repository, a list of registration authorities (RAI) that the repository if authoritative for, the permissions of the current user, and summery statistics about the types, counts, and revisions of items currently registered.

Registering Items

Administered items can be registered by authorized clients.

• RegisterItem - Register an administered item with the repository.

• RegisterItems - Register multiple administered items in a single web service call

Items are submitted by sending the DDI3 serialization of the item along with the item’s ISO 11179 IRDI, composed of the RAI, DI, and VI. An object type 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.

Retrieving Items

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

• GetItem - takes an ISO 11179 international registration data identifier (IRDI) and returns a RepositoryItem object containing information about an Administered Item and its XML serialization.

• GetLatestItem - takes only the RAI and DI portion of an IRDI, and returns a RepositoryItem object containing the latest revision of an administered item.

• GetItems and GetLatestItems - These calls take a collection of ISO 11179 IRDIs or RAI and DI pairs, and are for performance improvement. They can be used to substitute successive calls to their single item counterparts.

All four of these web service 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, object type, version date, version author, version rationale, published status, depreciated status, and repository authority information.

Note

Implementers Note: The identification information needed for these calls can be obtained from references in other objects, through an appropriate URN or by using the Colectica Repository’s search functionality, detailed below.

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.

• GetRepositoryItemDescription and GetRepositoryItemDescriptions - These calls take a single or collection of ISO 11179 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.

• GetRepositoryItemDescriptionsBySubject and GetRepositoryItemDescriptionsByObject - 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 RepositoryItems.

Set Management

Sets, similar to the RDF concept of a named graph, allow for the discovery of working sets. Named sets form the basis of process control in the Repository, allowing states such as development, production, HEAD, etc.

• GetSet - takes an ISO 11179 international registration data identifier (IRDI) that specifies the root item in the set and returns a list of IRDIs of items present.

• GetLatestSet - takes an ISO 11179 international registration data identifier (IRDI) that specifies the root item in the set and returns a list of IRDIs of items present. This special case of GetSet uses the latest version of any referenced administrative item in the object graph, and follows the latest item’s references when determining set boundaries.

Versioning

The Colectica Repository provides full support for item versioning.

• GetLatestVersionNumber - find the latest revision (VI) in the repository

• GetLatestVersionNumbers - find the latest revisions (VI) for a set of administered items. This is for increased performance for multiple calls of GetLatestVersionNumber

• GetVersions - retrieve a list of all IRDIs corresponding to the RAI - DI pair of an administered object

• GetVersionHistory - retrieve all RepositoryItemMetadata stored by the repository for all revisions of an item based on a RAI - DI pair.

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 Items

In order to provide complete audit functionality, repository items may not be 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.

• DepricateItem - marks an item as deprecated based on an ISO 11179 IRDI.

• RestoreItem - removes the deprecated status of an item based on an IRDI.

Search

The Colectica Repository offers advanced faceted search functionality.

• Search - The search method takes a collection of facets and search options, returning a search response.

• GetItemsForScheme - searches for items with the specified parent IRDI, and with the matching facet and search options

• GetRelationshipBySubject - 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.

• GetRelationshipByObject - 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.

The Search method returns a SearchResponse that is outlined below. The GetItemsForScheme method returns a collection of IRDIs that can be used to retrieve the administered items. The GetRelationship* methods return a collection of typed IRDIs. The parameters for the Search methods are listed below.

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

• 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 (DI)

• Agency identifier (RAI)

• Version number (VI)

• 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 or set of items 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.

• CreateTag - create a tag or tag set for an administered item

• GetTags - get a listing of tags for an administered item

• PublishItemGraph - verify all references in an administered item or set of items, and mark them as published.

Note

Implementers Note: To create a tag set, make sure that all references in the item graph are current by calling PublishItemGraph first.

Repository Item Annotations

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

• CreateComment - 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.

• GetComments - Get all comments about an Administered Item, and which revision they were applied to.

• CreateRating - Allows a user to rate an Administered Item for quality

• GetRatings - Get all ratings about an Administered Item, and which revision they were applied to.

Note

Implementers Note: User annotations are used for social collaboration using Colectica Web.