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
Service Composition Open API Specification (PRELIMINARY) - FIWARE Forge Wiki

Service Composition Open API Specification (PRELIMINARY)

From FIWARE Forge Wiki

Jump to: navigation, search
Disclaimer: The sustainability of this Open API Specification cannot be guaranteed due to internal changes in the project consortium.

Contents

Introduction to the Service Composition API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.

Service Composition API Core

The execution environment of the Service Composition exposes a basic life-cycle functionality for (composed) service descriptions including import/export and enabling/disabling them to be triggered for execution. The API is a RESTful, resource-oriented API accessed via HTTP. The end user can use the editor GUI to access this functionality in conjunction with the created or managed composition specifications, however this functionality can be used also from e.g. a Store GE to automatically deploy and enable a composite service after contracting.

The editor part of the Service Composition is a tool with a graphical user interface that is used to construct new composite services. Thus it does not expose an API per se, it allows the end user to construct the composite service descriptions using the GUI, and the data structure representing the skeleton and component services is also presented.

Intended Audience

This specification is intended for developers of the Service Composition or external components using it. Also, users creating compositions can understand the scope of the skeleton specification. To use this information, the reader should firstly have a general understanding of the Generic Enablers for Composition and Mashup. You should also be familiar with:

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

API Change History

Revision Date Changes Summary
May 3, 2012
  • Initial version
October 29, 2012
  • Revised 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 Service Composition architecture.

General Service Composition API Information

Resources Summary

The resources represent different skeleton and service descriptions. These can be deployed, retrieved, modified, and deleted from the execution environment. Moreover these can be enabled or disabled. Enabling a skeleton means that the service described by the skeleton can be triggered for execution. Enabling a service description means that this service can be considered as component service in the skeleton (i.e. when evaluating the service template constraints).

Data structure

The structure of the skeleton and services follows the model presented in the next figure. Note that constraints are specified by regular expression defining conditions under which the skeleton shall be executed during service composition. They are evaluated when the control flow reaches the

File:ServiceCompositionDataStructure.png
Service Composition Data Structure

Each skeleton element contains its own kind of skeleton parameters as described in the next table.

TypeNameValueUsed InMultiplicity
“call_parameter”<name><value>service template0..n
“result_var”-<value>service template0..1
“constraint”-<value>service template0..n
“condition”-<value>condition0..1
“condition_case”<case><next element>condition0..n
“goto”-<element reference>goto0..1
“ssmcommand_set”<name><value>ssm command0..1
“ssmcommand_remove”<name><value>ssm command0..1
“next”-<next element>all (except end)-

Authentication

Each HTTP request against the Service Composition 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. Some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

Authorization

It is assumed that access to the Service Composition GE is controlled by a authorization mechanisms in order to ensure that only authorized clients can read/modify/write specific information. The specification of a concrete authorization mechanism is out of scope for this document. Within the FI-WARE testbed, the authorization methods of the Security Chapter enablers will be supported by the Registry implementation.

Representation Format

The Service Composition GE API supports XML or JSON, for delivering information about services and skeletons. 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/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
  • application/xml - A XML description of the input and output.


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 skeleton descriptions are identified by the the following URI: /skeletons/{skeletonName}/{version} while the service descriptions are identified with the following URI: /services/{skeletonName}/{version}

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.

Extensions

The Registry 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 displaying to end users.

Fault ElementAssociated Error CodesExpected in All Requests?
Unauthorized403YES
Not Found404YES
Limit Fault413YES
Internal Server error50XYES

API Operations

Importing descriptions

Imports skeletons and service descriptions into the local description storage of the execution environment. If a skeleton/service with the same name and version is available in the local description storage its description will be updated. Note that we can use the function to add an entire set of resources.

Creating and Updating

Verb URI Description
PUT /{EntityType}/{Name}/{Version} Create or update one resource
PUT /{EntityType}/{Name} Crate or update a set of resources with the same name
PUT /{EntityType} Create or update a set of resources

Parameters

{EntityType} can be either "services" or "skeletons"

{Name} is the name of the service or skeleton

{Version} the version of the service or skeleton

Request Body

When creating/updating a resource the request body of a PUT operation should contain the set of attributes of the entry. E.g. if content-type was "application/json":

{
  "{attrName1}": "attrValue1",
  "{attrName2}": "attrValue2",
  ...
}

When creating/updating a set of resources the request body of a PUT operation contains an array of object attributes (if we update several versions of the object) or a nested array if we update several objects with different names and versions:

[
  {"acme_test_skel1": [
    {"v3.7": {
      "{attrName1}": "attrValue1",
      "{attrName2}": "attrValue2",
      ...
      }
    },
    {"v4.2": {
      ...
      }
    },
    ...
    ]
  },
  {"acme_test_skel2": [
    ...
    ]
  },
  ...
]

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

Exporting descriptions

Exports skeletons and service descriptions from the local description storage of the execution environment. Note that we can export also sets of resources, even distinguished by specific attribute name-value pairs.

Reading

Verb URI Description
GET /{EntityType}/{Name}/{Version} Read one resource
GET /{EntityType}/{Name} Read a set of resources with the same name
GET /{EntityType} Read a set of either service or skeleton descriptions
GET /{EntityType}?{attrName}={attrValue} Read a set of resources with specific attribute name-value pairs

Parameters

{EntityType} can be either "services" or "skeletons"

{Name} is the name of the service or skeleton

{Version} the version of the service or skeleton

Examples

GET /skeletons/ACME_test_skel1/v3.7

Returns the description of a specific skeleton.

GET /skeletons

Returns the description of all skeletons.

GET /services?serviceType=WSDL

Returns the descriptions of all services where serviceType is WSDL.

Result Format

The result format is similar to the request body examples given when importing descriptions.

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.

Removing descriptions

Removes skeletons and service descriptions from the local description storage of the execution environment. Note that we can remove also sets of resources, even distinguished by specific attribute name-value pairs. Only services and skeletons that are not enabled can be removed.

Deleting

Verb URI Description
DELETE /{EntityType}/{Name}/{Version} Delete a specific resource
DELETE /{EntityType}/{Name} Delete a set of resources with the same name
DELETE /{EntityType} Delete a set of either service or skeleton descriptions
DELETE /{EntityType}?{attrName}={attrValue} Delete a set of resources with specific attribute name-value pairs

Parameters

{EntityType} can be either "services" or "skeletons"

{Name} is the name of the service or skeleton

{Version} the version of the service or skeleton

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.

Enabling, disabling and checking enabled status

If a skeleton is set to enabled, it instantiates the composed application skeleton, exposes its interface and makes it ready to be triggered for execution. Only enabled skeletons will be considered during the skeleton execution. Note that by enabling a certain skeletons for execution, the GE automatically exposes the API of these compositions towards the external world, and any access to this API will trigger the execution of the respective skeleton. This is an API exposed by the execution environment, however it is created at runtime in the form specified by the composed service.

If a service is set to enabled it is considered as a potential candidate to match a "service template" when executing the skeleton.

By default all imported services and skeleton are considered disabled, and have to be enabled for use.

When disabling a skeleton the result may not be immediate if the composed service it represents is in use. Thus we need to check the enablement status before trying to remove a

Operations

Verb URI Description
PUT /{EntityType}/{Name}/{Version}/enabled Enable a certain service or skeleton
DELETE /{EntityType}/{Name}/{Version}/enabled Disable a certain service or skeleton
GET /{EntityType}/{Name}/{Version}/enabled Check if a certain service or skeleton is enabled

Parameters

{EntityType} can be either "services" or "skeletons"

{Name} is the name of the service or skeleton

{Version} the version of the service or skeleton

Request/Response Body

The request ore response body should be empty.

Status Codes

200 OK

The GET/DELETE request has been fulfilled. In case of GET it signals that the object is enabled.

201 Created

The PUT has been fulfilled and object is enabled.

202 Accepted

The request has been accepted for processing, but the processing has not been completed. Can appear when disabling a skeleton in use.

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. In case of get it signals that the object is disabled.

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