Services and APIs

#6. Services and APIs: Learning Registry Technical Specification V SA:0.50.1

See the Change Log for links to prior stable versions.

Major changes and additions from the prior version (0.24.0) are marked with ▲.

Significant deletions use strikethrough text.

Features to be deprecated in a future version are indicated with ▼.

This document is part of one or more versions of the Learning Registry Technical Specification. It may contain links to other parts of the Specification. These links may link to the most recent version of a part, not to the version of the part that corresponds to this version of this part. Go to the appropriate version of the Specification that links to this version of this part, and follow the links there to the referenced part to find the version of the part that corresponds to this version of this part.

This document is part of the Learning Registry Technical Specification. It is an introduction to the Learning Registry services.

This document is not standalone. The reader should be familiar with other parts of the specification, including, but not limited to:

• General Matter, including Licenses, Notation, Versioning, Glossary, References
• Resource Distribution Network Model
• Resource Data Data Models
• Identity, Trust, Authentication, Security
• Data Model and API Attributes and Behaviors
• Learning Registry Operations

Different types of services are detailed independently.

• Distribution
• Publish
• Access
• Broker
• Management/Administration/Discovery

6.1. Services and APIs

The services and their APIs provide the functionality that edge node producer and consumer agents use to push resource data into the distribution network and to discover and pull resource data from the network. They also define how to distribute the resource data throughout a network and how to manage, discover and observe resource distribution network behavior.

The specification defined types of services follows. Any non gateway node MAY provide any of these services. A node MAY provide additional services not specified herein.

• Distribution
  • Resource Data Distribution Service
• Publish
  • Basic Publish Service
  • Basic Delete Service
• Access
  • Basic Obtain Service
  • Basic Harvest Service
  • OAI-PMH Harvest Service
• Broker -- none currently defined
• Management/Administration/Discovery
  • Network Node Status Service
  • Network Node Description Service
  • Network Node Services Service
  • Resource Distribution Network Policy Service

NB: There is no mechanism to reserve names for APIs, tag them as authoritative (i.e., they are defined in this specification), etc. A future version of the specification MAY extend the service definition to include tags (e.g., authoritative, experimental, third-party) and other validation or conformance information.

Services and APIs are RESTful and bound to a particular node in the resource distribution network. Service descriptions include the API call (HTTP binding), the API arguments, the message payload (using the JSON-like notation), the service results (using JSON-like notation), error codes, an informative pseudo code description of a possible implementation, and the network node service description data.

The Network Node Service Description Data Model provides a machine and human readable description of the service; an instance of the description document is stored at the node that provides the service.

Additional constraints on API attributes, HTTP bindings (headers, HTTP errors), error processing and behaviors are described in the Data Model and API Attributes and Behaviors part of the specification.

Except as noted, services SHALL NOT be required to be provisioned at a node. An implementation SHALL NOT assume the provision of any service at any node, i.e., the implementation of one service cannot rely upon another service.

▲Except as noted, services SHALL be fully independent; the implementation and provisioning of a service at a node SHALL NOT assume that any other service is deployed at the node.

6.2. Change Log

NB: The change log only lists major updates to the specification.

NB: Updates and edits may not results in a version update.

NB: See the Learning Registry Technical Specification for prior change history not listed below.

Version	Date	Author	Change
	20110921	DR	This document extracted from the monolithic V 0.24.0 document. Archived copy (V 0.24.0)
0.50.0	20110927	DR	Editorial updates to create stand alone version. Clarify non dependence of service deployment.Archived copy location TBD. (V SA 0.50.0)
Future	TBD		Archived copy location TBD. (V SA:x.xx.x)
0.50.1	20130312	JK	This document extracted from Google Doc and converted to RestructuredText. Archive copy (V SA:0.50.0)

6.3. Working Notes and Placeholder Text