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

FIWARE.OpenSpecification.Apps.MarketplaceReviewAndRatingREST

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Marketplace Review and Rating 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 Review and Rating Core

The Marketplace Review and Rating Component is a RESTful, resource-oriented API accessed via HTTP that uses various representations for information interchange. The Review and Rating component allows users of the marketplace to give textual and star-rating feedback for user defined objects. These objects are not necessarily, but may be also a part of the marketplace itself (e.g. stores or services). Reviews of users and their ratings are being used to improve the quality of the recommendation component.

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 Review and Rating API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Nov 11, 2013
  • 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 Marketplace.

Additional Resources

You can download the most current version of this document from the FI-WARE API specification website at Marketplace Review and Rating 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 Review and Rating 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 Review and Rating component is described in this document.

Resources Summary

The Review and Rating component allows users of the marketplace to give textual and star-rating feedback for services and stores along defined categories. Reviews of users and their overall rating about applications and services can be used to improve the quality of the recommendation.

Image:MarketplaceRating_Interface.png

  • Object Categories are used to cluster user review and ratings
  • Rating Categories are always tight to a Object Category and are used to allow users to rate opbjects along different categories.
  • Rating Objects are concrete objects which can be rated. A Rating Object is tight to exacty one Object Category.

Authentication

Each HTTP request against the Marketplace Review and Rating 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 Review and Rating 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 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/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 Review and Rating 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 under the URL http://marketplaceRegistration.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 Registration.

Setting up resolvers is more complex task. Therefore we try to follow a simpler approach for the USDLMarketplace RegistrationRest. 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).

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 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 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
Not Found406 Not Acceptable
Not Found412 Precondition Failed
Limit Fault413YES
Internal Server error50XYES


API Operations

Creating Rating Objects

In this section we describe how to create reviews, ratings, categories, object categories and rating objects.


Verb URI Description
POST/PUT /rating/objectCategory/{ObjectCategoryName} Create a new Rating Object Category
POST/PUT /rating/objectCategory/{ObjectCategoryName}/category

/{RatingCategoryName}

Create a new Rating Category
POST/PUT /rating/objectCategory/{ObjectCategoryName}/object

/{ObjectName}

Create a new Rating Object
POST/PUT /rating/objectCategory/{ObjectCategoryName}/object

/{ObjectName}/rating/

Create a new Rating, Rating ID needs to be returned in the result
POST/PUT /rating/objectCategory/{ObjectCategoryName}/object

/{ObjectName}/rating/{RatingId}/category/{RatingCategoryName}/stars/{STARS}

Create Rating for Category
POST/PUT /rating/objectCategory/{ObjectCategoryName}/object

/{ObjectName}/rating/{RatingId}/textualReview/{Review_Message}

Create Textual Review


Receiving Rating Objects

In this section we describe how to get reviews, ratings, categories, object categories and rating objects.


Verb URI Description
GET /rating/objectCategory/{ObjectCategoryName}

/object/{ObjectName}/rating/{RatingId}

Get a Rating
GET /rating/objectCategory/{ObjectCategoryName}

/category/{RatingCategoryName}/Quality

Get a Category
GET /rating/objectCategory/{ObjectCategoryName}

/object/{ObjectName}

Get a Rating Object
GET /rating/objectCategory/{ObjectCategoryName} Get a Rating Object Category
GET /rating/objectCategory/{ObjectCategoryName}

/object/{ObjectName}/ratings

Get all Ratings for an Object
GET /rating/objectCategory/{ObjectCategoryName}/objects Get all Objects for an Object Category
GET /rating/objectCategory/{ObjectCategoryName}/categories Get all Categories for an Object Category
GET /rating/objectCategories Get all Available Object Categories

Deleting Rating Objects

In this section we describe how to delete reviews, ratings, categories, object categories and rating objects. All deletion operations must be cascading.

Verb URI Description
DELETE /rating/objectCategory/{ObjectCategoryName}

/object/{ObjectName}/rating/{RatingId}

Delete a Rating
DELETE /rating/objectCategory/{ObjectCategoryName}

/{RatingCategoryName}/Quality

Delete a Rating Category
DELETE /rating/objectCategory/{ObjectCategoryName}

/object/{ObjectName}

Delete a new Rating Object
DELETE /rating/objectCategory/{ObjectCategoryName} Delete a new Rating Object Category


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.

406: Not Acceptable

The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.

409 Conflict

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

412: Precondition Failed

The server does not meet one of the preconditions that the requester put on the request.

500 Internal Server Error

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