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

FIWARE.OpenSpecification.Apps.ApplicationMashupAPI

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Application Mashup API

Please check the following FI-WARE Open Specification Legal Notice (implicit patents license) to understand the rights to use this open specification.

UPM strives to make 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. This GE specification should be implementable without requiring patent pledges. However, the Copyright Holder of this spec (UPM) is not responsible for identifying patents for which a license may be required for any implementation of this specification.

Application Mashup Core

The Application Mashup GE offers two separate APIs that cannot be combined because of their different nature: The Widget API is a JavaScript API, while the Application Mashup API (the subject of this entry) is a RESTful one. You can find the Widget API in this separate entry:

The Application Mashup API is a RESTful, resource-oriented API accessed via HTTP that uses various representations for information interchange. This API provides the functionality to create and modify workspaces and the functionality to manage the resources available for building these workspaces.

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

Revision Date Changes Summary
Jun 28, 2013
  • Changed error response format and used error codes
Apr 18, 2013
  • Revised version
Nov 2, 2012
  • Initial 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 the Application Mashup GE description.

Additional Resources

You can download the most current version of this document from the FI-WARE API specification website at Application Mashup API. For more details about the Application Mashup GE that this API is based upon, please refer to the Application Mashup GE description.

High Level Description. Related documents, including an Architectural Description, are available at the same site.

General Mashup Application API Information

Resources Summary

The following figure summarizes the resources considered in the Application Mashup RESTful API

Authentication

Each HTTP request against the Application Mashup 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 the provider to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operates using SSL over HTTP (HTTPS).

Representation Format

The Application Mashup API supports at least JSON for delivering any kind of resources, it may also support simple text, XML 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.

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.
  • application/x-www-form-urlencoded - May be used for submitting using HTML forms.
  • multipart/form-data - Should be used for submitting HTML forms containing files.
  • application/octet-stream - Used for uploading/downloading packaged Mashable Application Components.


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

The Application Mashup API is relying on Web principles:

  • consistent URI structure based on REST style protocol
  • HTTP content negotiation to allow the client to choose the appropriate data format supporting XML, JSON, ...

Limits

The capacity of the system can be managed 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.

Versions

The Mashup Application API is considered to be an extension of itself, so the current version of the Mashup Application API can be queried using the resource described in the next section. The core extension defining the Mashup Application API is known as "ApplicationMashup".

Extensions

The Application Mashup GE can be extended. The Application Mashup GE provides the resource described below. This allows 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 /api/featuresList of all available extensions

Example request:

GET /api/features HTTP/1.1
Accept: application/json

Example response:

200 OK
Content-Type: application/json

{
    "ApplicationMashup": "1.0"
}

Faults

Synchronous Faults

Error responses will be encoded using the most appropriated content-type in base to the Accept header of the request. In any case, the response will provide a human-readable message for displaying to end users.

XML Example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
   <description>Missing dependencies</description>
   <details>
       <missingDependencies>
           <element>Wirecloud/nonavailable-operator/1.0</element>
           <element>Wirecloud/nonavailable-widget/1.0</element>
       </missingDependencies>
   </details>
</error>

JSON Example:

{
    "description": "Missing dependencies",
    "details": {
       "missingDependencies": [
           "Wirecloud/nonavailable-operator/1.0",
           "Wirecloud/nonavailable-widget/1.0"
       ]
    }
}
Fault ElementAssociated Error CodesExpected in All Requests?
Bad Request400YES
Unauthorized401YES
Forbidden403YES
Not Found404YES
Conflict409NO
Request Entity Too Large413YES
Unprocessable Entity422NO
Internal Server error50XYES

API Operations

Managing Workspaces

The description of the operations is shown in the next table:

Verb URI Description Mandatory/optional
GET /api/workspaces Get the list of workspaces available for the user Mandatory
POST /api/workspaces Create a new workspace Mandatory
GET /api/workspace/{workspace_id} Get info about a specific workspace Mandatory
DELETE /api/workspace/{workspace_id} Delete a workspace Mandatory
PUT /api/workspace/{workspace_id}/wiring Updates workspace wiring configuration Mandatory
POST /api/workspace/{workspace_id}/tabs Create a new workspace tab Mandatory
DELETE /api/workspace/{workspace_id}/tab/{tab_id} Delete a workspace tab Mandatory
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidgets Add a new instance of a widget into the tab Mandatory
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id} Update widget instance status Mandatory
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/preferences Update widget instance preferences Mandatory
DELETE /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id} Removes an instance of widget from a tab Mandatory

Getting Workspaces

Example request:

GET /api/workspaces HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

[
  {
      "name":"tourist_app",
      "creator":"sptel",
      "owned":false,
      "removable":false,
      "active":true,
      "shared":true,
      "id":20
  }
]

Creating Workspaces

Request parameters:

  • mashup (String): Id of the mashup to use as base for creating the workspace. This option cannot be used along workspace.
  • workspace (String): Id of the workspace to use as base for creating the new workspace. This option cannot be used along mashup.
  • name (String): Name for the new workspace. This parameter is optional if either mashup or workspace is used. In those cases, the name will be obtained from the referenced mashup or workspace.
  • allow_renaming (Boolean; default: false): If false, any attempt to create a workspace using a currently used name will fail. If this parameter is true and the name is already in use, a new name will be computed using the indicated name as base.

Creating Workspaces from scratch

Example request:

POST /api/workspaces HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "name": "test"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "name":"test",
   "creator":"admin",
   "wiring":{"operators": {}, "connections": []},
   "empty_params":[],
   "active":false,
   "shared":false,
   "tabs":[
      {
         "visible":true,
         "iwidgets":[],
         "id":84,
         "name":"Tab",
         "preferences":{}
      }
   ],
   "id":81,
   "extra_prefs":{},
   "preferences":{}
}

Creating Workspaces from Mashups

Example request:

POST /api/workspaces HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "mashup": "UPM/Mashup/1.0"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "name":"example",
   "creator":"admin",
   "wiring":{"operators": {}, "connections": []},
   "empty_params":[],
   "active":false,
   "shared":false,
   "tabs":[
      {
         "visible":true,
         "iwidgets":[
               {
                  "widget":"UPM/Widget1/0.1",
                  "layout":0,
                  "name":"Widget1",
                  "icon_top":-1,
                  "variables":{},
                  "minimized":false,
                  "id":311,
                  "height":28,
                  "zIndex":0,
                  "width":6,
                  "readOnly":false,
                  "icon_left":-1,
                  "tab":3,
                  "transparency":false,
                  "refused_version":null,
                  "top":0,
                  "fulldragboard":false,
                  "left":0
               },
               {
                  "widget":"UPM/Widget2/0.1",
                  "layout":0,
                  "name":"Widget2",
                  "icon_top":-1,
                  "variables":{},
                  "minimized":false,
                  "id":312,
                  "height":28,
                  "zIndex":0,
                  "width":6,
                  "readOnly":false,
                  "icon_left":-1,
                  "tab":3,
                  "transparency":false,
                  "refused_version":null,
                  "top":0,
                  "fulldragboard":false,
                  "left":7
               }
         ],
         "id":100,
         "name":"Tab",
         "preferences":{}
      }
   ],
   "id":50,
   "extra_prefs":{},
   "preferences":{}
}

Notes:

'UPM/Mashup/1.0' is a mashup available on the local catalogue of the user.

Copying Workspaces

Example request:

POST /api/workspaces HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "workspace": "3"
}

Example response:


Notes:

'3' is the id of a workspace accesible to the authenticated user.

Getting Workspace details

Example request:

GET /api/workspace/81 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   "name":"test",
   "creator":"admin",
   "wiring":"{\"operators\": {}, \"connections\": []}",
   "empty_params":[],
   "active":false,
   "shared":false,
   "tabs":[
      {
         "visible":true,
         "iwidgets":[],
         "id":84,
         "name":"Tab",
         "preferences":{}
      }
   ],
   "id":81,
   "extra_prefs":{},
   "preferences":{}
}

Deleting Workspaces

Example request:

DELETE /api/workspace/81 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 204 No Content

Updating Workspace Wiring Configuration

Example request:

PUT /api/workspace/81/wiring HTTP/1.1
Content-Type: application/json
Accept: application/json

{
   "operators":{
      "0":{
         "name":"UPM/Operator/0.1",
         "id":"0"
      }
   },
   "connections":[
      {
         "source":{
            "type":"iwidget",
            "id":311,
            "endpoint":"location_info_event"
         },
         "target":{
            "type":"iwidget",
            "id":312,
            "endpoint":"search_text_slot"
         }
      },
      {
         "source":{
            "type":"iwidget",
            "id":311,
            "endpoint":"location_info_event"
         },
         "target":{
            "type":"ioperator",
            "id":0,
            "endpoint":"message"
         }
      }
   ]
}

Example response:

HTTP/1.1 204 No Content

Notes:

'UPM/Operator/1.0' is a operator available on the local catalogue of the user.

Creating Workspace Tabs

Request parameter:

  • name (String): Name for the new tab. This parameter is required.

Example request:

POST /api/workspace/81/tabs HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "name": "Tab 2"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "id": 3,
   "name":"Tab 2"
}

Deleting Workspace Tabs

Example request:

DELETE /api/workspace/81/tab/3 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 204 No Content

Adding a New Instance of Widget into a Workspace Tab

POST /api/workspace/81/tab/3/iwidgets HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "widget": "UPM/Widget/1.0"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "widget":"UPM/Widget/1.0",
   "left":12,
   "top":0,
   "icon_left":-1,
   "icon_top":-1,
   "zIndex":2,
   "width":6,
   "height":28,
   "name":"Widget",
   "layout":0
}

Notes:

'UPM/Widget/1.0' is a widget available on the local catalogue of the user.

Updating Widget Instances

Request parameters:

  • name (String): Name given to the instance of Widget.
  • tab (String): Id of the tab where the widget is going to be hosted. Widgets can only be moved between tabs of the same workspace.
  • width (Number):
  • height (Number):
  • top (Number):
  • left (Number):
  • zIndex (Number):

Example request:

POST /api/workspace/81/tab/3/iwidget/5 HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "name": "new name"
}

Example response:

HTTP/1.1 204 No Content

Updating Widget Instance Preferences

Example request:

POST /api/workspace/81/tab/3/iwidget/5/preferences HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "pref": "value"
}

Example response:

HTTP/1.1 204 No Content

Removing Widget Instances From Workspace Tabs

Example request:

DELETE /api/workspace/81/tab/3/iwidget/5 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 204 No Content

Managing Local Catalogue

Verb URI Description Mandatory/optional
GET /api/resources Get a list of all resources (widgets, operators, etc.) available to the user Mandatory
POST /api/resources Add a resource (widget, operator, etc.) to the local catalogue of the user Mandatory
GET /api/resource/{MAC_id} Download a resource (widget, operator, etc.) from the local catalogue of the user Mandatory
DELETE /api/resource/{MAC_id} Uninstall a resource (widget, operator, etc.) from the local catalogue of the user Mandatory

Obtaining the list of Mashable Application Components

Example request:

GET /api/resources HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "CoNWeT/multimedia-viewer/0.5": {
      "type": "widget",
      "vendor":"CoNWeT",
      "name":"multimedia-viewer"
      "version":"0.5",
      "description":"This widget allows watch youtube videos, flickr images and another images.",
      "variables":{
         "urlEvent":{
            ....
         },
         "uriEvent":{
            ....
         },
         "apikeyPref":{
            ....
         },
         "uriSlot":{
            ....
         },
         ....
      },
      ...
   },
   "UPM/Operator/1.0": {
      "type": "operator",
      "vendor":"UPM",
      "name":"Operator"
      "version":"1.0",
      ...
   }
}

Uploading Mashable Application Components

Example request:

POST /api/resources HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryHPwaOXLATyUcGQp8
Accept: application/json

------WebKitFormBoundaryHPwaOXLATyUcGQp8
Content-Disposition: form-data; name="file"; filename="widget.wgt"
Content-Type: application/octet-stream

    ...

------WebKitFormBoundaryHPwaOXLATyUcGQp8--

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "type": "operator",
   "vendor":"UPM",
   "name":"Widget"
   "version":"1.0",
   ...
}

Exporting Mashable Application Components

Example request:

GET /api/resource/UPM/Widget/1.0 HTTP/1.1
Accept: application/octet-stream

Example response:

HTTP/1.1 200 OK
Content-type: application/octet-stream
Vary: Accept, Cookie

   ...

Uninstalling Mashable Application Components

Example request:

DELETE /api/resource/UPM/Widget/1.0 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 204 No Content

Status Codes

200 OK

The request was handled successfully and transmitted in response message.

201 Created

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

204 No Content

The server successfully processed the request, but did not return any content.

304 Not Modified

Indicates the resource was not 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. Use of this feature saves bandwidth and reprocessing on both the server and client side, as only the header data must be sent and received in comparison to the entire page being re-processed by the server, then sent again using more bandwidth of the server and client.

400 Bad Request

The request could not be fulfilled due to bad syntax.

401 Unauthorised

The request requires user authentication. If the request already included Authorization credentials, then the 401 response indicates that authorization was refused for those credentials.

403 Forbidden

The server understood the request, but is refusing to fulfill it because the user doesn’t have permission to perform the requested action.

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 already taken name.

413 Request Entity Too Large

The request is larger than the server is willing or able to process.

422 Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors.

500 Internal Server Error

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