We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.OpenSpecification.Apps.RegistryREST - FIWARE Forge Wiki

FIWARE.OpenSpecification.Apps.RegistryREST

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Registry API

Registry API Core

The Registry API is a RESTful, resource-oriented API accessed via HTTP that uses various representations for information interchange.

Overall description of the API with its functionalities.

Intended Audience

This specification is intended for both software developers and Cloud Providers. For the former, this document provides a full specification of how to interoperate with Cloud Platforms that implements the Registry API. For the latter, this specification indicates the interface to be provided in order to clients to inter-operate with Cloud Platform to provide the described functionality. To use this information, the reader should firstly have a general understanding of the Generic Enabler service FIWARE.ArchitectureDescription.Apps.Registry. You should also be familiar with:

  • ReSTful web services
  • HTTP/1.1
  • JSON and/or XML data serialization formats.
  • LDAP

API Change History

This version of the Registry API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 20, 2012
  • Initial version

How to Read This Document

In the whole document it is taken the assumption that reader is familiarized with REST architecture style. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.
  • <add any other content that you think that it is relevant>

For a description of some terms used along this document, see FIWARE.ArchitectureDescription.Apps.Registry.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php?title=FIWARE.OpenSpecification.Apps.RegistryREST . For more details about the Registry GE that this API is based upon, please refer to <link to the High Level Description>. Related documents, including an Architectural Description, are available at the same site.

General Registry API Information

Resources Summary

The registry is structured into core objects, which are called registry entries. These objects constitute also the granularity of access control. A registry entry, uniquely identified by its distinguished name, can hold a number of attributes.

Authentication

Each HTTP request against the Registry GE requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token) and will be determined by the specific provider that implements the GE. Please contact with it to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

Authorization

It is assumed that access to the registry is controlled by a authorization mechanisms in order to ensure that only authorized clients can read/modify/write specific information.

The FI-WARE configuration requires OAuth2 API authorization with Bearer tokens, which have to be sent with each request. The token will be validated against the FI-WARE Identity Management Generic Enabler running in the FI-WARE Lab.

Example request header:

   Authorization: Bearer AbCdEf123456

Representation Format

The Registry API supports XML/RDF, Turtle, JSON, Atom HTML for delivering information for registry entries. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the Accept header. Note that it is possible for a response to be serialized using a format different from the request (see example below).

If no Content-Type is specified, the content is delivered in the format that was choosen to upload the resource.

The interfaces should support data exchange through multiple formats:

  • text/plain - A linefeed separated list of elements for easy mashup and scripting.
  • text/html - An human-readable HTML rendering of the results of the operation as output format.
  • application/json - A JSON representation of the input and output for mashups or JavaScript-based Web Apps
  • application/rdf+xml - A RDF description of the input and output.


Other formats such as XML, RSS, Atom, etc. are possible.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

This section must explain which would be the resource identification used by the API in order to identify unambiguously the resource. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

The Distinguished Entry Name (DEN) is used to unambiguously identify registry entries. In analogy to the LDAP protocol (RFCs 4510,4512,4514,4516,4517) we assume distinguished entry names can be expressed in a hierarchical way.

Example:

/c=de/o=University%20of%20Michigan - is a DEN similar to an LDAP DN

/de/University%20of%20Michigan - is an alternative representation of the DEN assuming that there is a default hierarchy

Links and References

Web citizen

The registry is relying on Web principles:

  • URI to identify resources
  • consistent URI structure based on REST style protocol
  • HTTP content negotiation to allow the client to choose the appropriate data format supporting HTML, RDF, XML, RSS, JSON, Turtle, ...
  • Human readable output format using HTML rendering ('text/html' accept header) including hyperlinked representation
  • Use of HTTP response codes including ETags (proper caching)
  • Linked Data enablement supporting RDF input and output types

Paginated Collections

In order to reduce the load on the service, we can decide to limit the number of elements to return when it is too big. This section explain how to do that using for example a limit parameter (optional) and a last parameter (optional) to express which is the maximum number of element to return and which was the last element to see.

These operations will have to cope with the possibility to have over limit fault (413) or item not found fault (404).

Limits

We can manage the capacity of the system in order to prevent the abuse of the system through some limitations. These limitations will be configured by the operator and may differ from one implementation to other of the GE implementation.

Rate Limits

These limits are specified both in human readable wild-card and in regular expressions and will indicate for each HTTP verb which will be the maximum number of operations per time unit that a user can request. After each unit time the counter is initialized again. In the event a request exceeds the thresholds established for your account, a 413 HTTP response will be returned with a Retry-After header to notify the client when they can attempt to try again.

Faults

Synchronous Faults

In this section, we provide the complete list of possible fault elements and error code, and if it is expected in all request or not following this table.

Fault ElementAssociated Error CodesExpected in All Requests?
GET /limits[YES]

We must indicate which will be the fault response in XML and/or JSON format and it would be nice if we can provide some type of information associated to the specific error including a message and details.

API Operations

In this section we go in depth for each operation. In order to provide good comprehensive of the API operations, we would suggest to group them into similar functionalities within subsections. e.g. operations related to VM management in the Cloud Chapter or Context Entity Management in IoT.

Retrieving Registry Information

Read registry entry

Here we start with the description of the operation following the next table:

Verb URI Description
GET /{DistinguishedEntryName}?filter={FilterExpression}&attributes={AttributeList}&scope={Scope} Get registry entry information:

Paramters

FilterExpression - Expression for filtering registered entries under a relative distinguished entry name.

AttributeList - Comma-separated list of attribute names which should be returned.

Scope - Return entries of the DEN only or in the whole sub-tree (one of "base" / "one" / "sub")

Example

GET /de/service/stores/?attributes=Name,serviceResource,endpoint

Returns the name, service description URL, and service endpoint URL for all services registered under "/de/service/stores".

Result Format

Accept: application/json:

[ { DEN: "/de/service/stores/store1",
    Name: "Store1 Name",
    service: "http://fiware.org/usdl/servicestorexyz",
    endpoint: "http://fiware-platform.org/service/store1/instance4711"
  },
  ...
]

Error Codes

200 OK

The request was handled successfully and transmitted in response message.

400 Bad Request

The request cannot be fulfilled due to bad syntax.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.

Modifying Entries

Creating and Updating

Verb URI Description
PUT /{DistinuguishedEntryName} Create or update a resource or a number of resources

Request Body

The request body of a PUT operation should contain the set of attributes of the entry. E.g. if Content-type was "application/json":

{
  "{attributeName1}": "AttributeValue1",
  "{attributeName2}": "AttributeValue2",
  ...
}

or for a number of resources

[{
  "RDN": "{RelativeDistinguishedName",
  "{attributeName1}": "AttributeValue1",
  "{attributeName2}": "AttributeValue2",
  ...
 },
 ...
]

respectively.

Error Codes

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The request cannot be fulfilled due to bad syntax.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.


Adding Information

Verb URI Description
POST /{DistinguishedEntryName} Add attributes to a registry entry

Request Body

The request body contains the attributes to be added to an entry:

{
  "{attributeName1}": "AttributeValue1",
  "{attributeName2}": "AttributeValue2",
  ...
}

Error Codes

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The request cannot be fulfilled due to bad syntax.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.

Deleting Registry Information

Deleting Entries

Verb URI Description
DELETE /{DistinuguishedEntryName} Delete a registry entry

Error Codes

200 OK

The request was handled successfully and transmitted in response message.

400 Bad Request

The request cannot be fulfilled due to bad syntax.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.

Delete Attributes of an Entry

Verb URI Description
DELETE /{DistinguishedEntryName}?attributes={AttributeNames} Delete attributes of a registry entry

Parameters

{AttributeNames} contains a comma-separated list of attribute names to be deleted from the entry.

Error Codes

200 OK

The request was handled successfully and transmitted in response message.

400 Bad Request

The request cannot be fulfilled due to bad syntax.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.
Personal tools
Create a book