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.RepositoryREST - FIWARE Forge Wiki

FIWARE.OpenSpecification.Apps.RepositoryREST

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Repository API

Please check the following FI-WARE Open Specification Legal Notice (essential patents license) to understand the rights to use this open specification. As all other FI-WARE members, SAP has chosen one of the two FI-WARE license schemes for open specifications.

To illustrate this open specification license from our SAP perspective:

  • SAP provides the specifications of this Generic Enabler available under IPR rules that allow for a exploitation and sustainable usage both in Open Source as well as proprietary, closed source products to maximize adoption.
  • This Open Specification is exploitable for proprietary 3rd party products and is exploitable for open source 3rd party products, including open source licenses that require patent pledges.
  • If the owner (SAP) of this GE spec holds a patent that is essential to create a conforming implementation of the GE spec (i.e. it is impossible to write a conforming implementation without violating the patent) then a license to that patent is deemed granted to the implementation.

Repository API Core

The Repository API is a RESTful, resource-oriented API accessed via HTTP that uses various representations for information interchange. The Repository provides a consistent uniform API to USDL service descriptions and associated media files.

Intended Audience

This specification is intended for both software developers and reimplementers of this API. For the former, this document provides a full specification of how to interoperate with products that implement the Repository API. For the latter, this specification indicates the interface to be implemented and provided to clients.

To use this information, the reader should firstly have a general understanding of the Generic Enabler service Repository. You should also be familiar with:

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

API Change History

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

Revision Date Changes Summary
Apr 2, 2012
  • Initial version
Apr 03, 2014
  • Final version

How to Read This Document

It is assumed that the reader is familiar with the REST architecture style. Within 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.
  • Variables are represented between brackets, e.g. {id} and in italic font. The reader can replace the id with an appropriate value.

For a description of some terms used along this document, see Repository.

Additional Resources

You can download the most current version of this document from the FI-WARE API specification website at Repository API . For more details about the Repository GE that this API is based upon, please refer to High Level Description. Related documents, including an Architectural Description, are available at the same site.

General Repository API Information

Resources Summary

The repository is structured into core objects, which are resources, and collections. These objects constitute also the granularity of access control. Collections are containers for storing resources. Any object can provide services such as search, query, transform, maintain, depending on the type of the resource.

Resources

The resources are mainly the USDL service descriptions themselves as well as complementary media files that are used within the service descriptions.

Collections

A collection is a container for collecting resources and other collections. Multiple collections can be used on the repository for various purposes. Collections provide versioning of the resources.

Graphical diagram in which the different URIs that can be used in the API is shown here.

Schematic resoure tree of the Repository

Authentication

Each HTTP request against the Repository GE requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token). It is left open how authentication is realized. In practice ith will be determined by the specific environment and the provider implementing the GE. Some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

Representation Format

The Repository API supports XML and JSON for delivering metadata resources and any kind of media type for media resources, it may also support RDF, Turtle (http://www.w3.org/TeamSubmission/turtle/) and Atom (http://tools.ietf.org/html/rfc4287) HTML for delivering metadata. 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.


In a concrete implementation of this GE other formats like RSS, Atom, etc. may also be 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

The resource identification for HTTP transport is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Links and References

Web citizen

The repository 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

Linked Open Data

Publishing data as linked data requires every resource to be directly resolvable given their URL. The basic idea of Linked Data is simple. Tim Berners-Lee’s note on Linked Data (http://www.w3.org/DesignIssues/LinkedData) describes four rules for publishing data on the Web:

  • Use URIs as names for things
  • Use HTTP URIs so that people can look up those names.
  • When someone looks up a URI, provide useful information, using the standards (RDF*, SPARQL)
  • Include links to other URIs, so that they can discover more things.

This can actually achieved by different approaches. One is the use of a special resolver similar to URL shorteners.

So the authoring environment has to ensure that every URI (actually IRI - Internationalized Resource Identifiers - RFC 3987) can be resolved by a HTTP GET request. For example: If a resource is maintained in a repository under the URL http://repository.acme.com/service/xyz but the IRI used in service descriptions is actually http://fi-ware.org/service/xyz, we need a resolver at this location which redirects the request to the actual repository.

Setting up resolvers is more complex task. Therefore we try to follow a simpler approach for the USDLRepositoryRest. The API is designed to be directly used for Linked Data publishing without the need for a resolver.

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.

ETag Handling

For standard caching an ETag HTTP header is provided for GET and PUT requests. If a GET requests has a "If-None-Match" header, than the content is only delivered if the stored ETag of the object matches the requested ETag. HTTP status code 304 (not changed) is responded otherwise.

For PUT requests the ETag header can be used to ensure integrity of the repository. The PUT operation will only be executed if the "If-Match" header matches the stored ETag of the resource in the repository. If no "If-Match" header is given for an existing resource or the "If-Match" header does not match the existing ETag of the resource, status code 409 (Conflict)will be returned. If the resource was changed, then a new ETag header will be returned in the response header.

Extensions

The Repository could be extended in the future. At the moment, we foresee the following resource to indicate a method that will be used in order to allow the extensibility of the API. This allow the introduction of new features in the API without requiring an update of the version, for instance, or to allow the introduction of vendor specific functionality.

VerbURIDescription
GET /extensionsList of all available extensions

Faults

Synchronous Faults

Error codes are returned in the body of the response. The description section returns a human-readable message for displaing end users.

Example:

<exception>
	<description>Resource Not found</description>
	<errorCode>404</errorCode>
	<reasonPhrase>Not Found</reasonPhrase>
</exception>
Fault ElementAssociated Error CodesExpected in All Requests?
Unauthorized403YES
Not Found404YES
Limit Fault413YES
Internal Server error50XYES


API Operations

Managing Collections

Verb URI Description
GET /{CollectionPath} Get a collection
PUT /{CollectionPath} Create or update a collection
DELETE /{CollectionPath} Delete a collection


Status Codes

200 OK

The request was handled successfully and transmitted in response message.

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.

304 Not Modified

Indicates the resource has not been modified since last requested. Typically, the HTTP client provides a header like the If-Modified-Since header to provide a time against which to compare. Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received in comparison to the entirety of the page being re-processed by the server, then sent again using more bandwidth of the server and client.

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.

Managing Resources

Verb URI Description
GET /{CollectionPath}/{ResourceID} Get a resource
PUT /{CollectionPath}/{ResourceID} Create or update a resource
DELETE /{CollectionPath}/{ResourceID} Delete a resource

Status Codes

200 OK

The request was handled successfully and transmitted in response message.

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.

304 Not Modified

Indicates the resource has not been modified since last requested. Typically, the HTTP client provides a header like the If-Modified-Since header to provide a time against which to compare. Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received in comparison to the entirety of the page being re-processed by the server, then sent again using more bandwidth of the server and client.

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.

Additional Services

Verb URI Description
GET /{collectionPath}/services Get a list of additional services in e.g. USDL format


Status Codes

200 OK

The request was handled successfully and transmitted in response message.

500 Internal Server Error

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

Searching the Repository

Verb URI Description
GET /{CollectionPath}/search?q={queryString} Search a collection


Status 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