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


From FIWARE Forge Wiki

Jump to: navigation, search


Introduction to the Marketplace Offering 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.

Marketplace Offering Core

The Marketplace Offering API is a RESTful, resource-oriented API accessed via HTTP that uses various representations for information interchange. The Marketplace Offerings Component is responsible for exchanging service offerings with stores and making them public to potential customers.

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 Marketplace. You should also be familiar with:

  • RESTful web services
  • HTTP/1.1
  • JSON and/or XML data serialization formats.
  • RDF, TURTLE and Atom

API Change History

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

Revision Date Changes Summary
Apr 25, 2012
  • Initial version
Apr 21, 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 Marketplace.

Additional Resources

You can download the most current version of this document from the FI-WARE API specification website at Marketplace Offerings API . For more details about the Marketplace 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 Marketplace Offering API Information

The Marketplace GE is structured into five core components. These components are Registry & Directory, Offering & Demand, Discovery & Matching, Recommendation, and the Review and Rating component. The API for the Offering & Demand component is described in this document.

Resources Summary

A service offering consists of a link to a concrete USDL description, a pricing model and the classification of the service. The Offering component is responsible for exchanging service offerings with stores and version handling/archiving of out-dated offerings. Symmetrically to offerings also the demand side of the marktet need to be represented. A service demand according to expected functionality, pricing and service levels might be expressed, classified and published to the marketplace.


Each HTTP request against the Marketplace Offering API 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).

Representation Format

The Marketplace Offering API supports at least XML and JSON for delivering any kind of resources, it may also support simple text and HTML output format. 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 chosen 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/xml - A XML 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 Marketplace Offering 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 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 Marketplace Offering under the URL http://marketplaceOffering.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 Marketplace Offering.

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

Paginated Result Lists

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).


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.


The Marketplace 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 will 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.

GET /extensionsList of all available extensions


Synchronous Faults

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


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

API Operations

Managing Offerings

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

Verb URI Additional Path Parameters Description
GET /offering/ filter, index, limit Get a list of all offerings
GET /offering/store/{storeName}/offerings filter, index, limit Get a list of all offerings from a specific store
GET /offering/store/{storeName}/offering/{offering} - Get a specific offering
GET /offering/store/{storeName}/offering/{offering}/history version Get the history of a specific offering
PUT /offering/store/{storeName}/offering/{offering} - Create a new offering (offering information in body)
POST /offering/store/{storeName}/offering/{offering} - Update offering information, creates a new version
DELETE /offering/store/{storeName}/offering/{offering} - disables an offering

A Filter expression, a limit and a starting index are supported for the /offerings/ and the /offerings/store/{storeName}/offerings operation to reduce the number of results. If no filter expression is given then all users are returned.

  • filter - Optional filter expression to reduce the number of delivered results.
  • index - Index of the first rating to be returned.
  • limit - Maximal number of results to be returned.



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.
Personal tools
Create a book