FIWARE Application Mashup RESTful v2.2 Specification

DATE: 16th October 2017
This version:
http://wirecloud.github.io/wirecloud/restapi/v2.2
Previous version:
http://wirecloud.github.io/wirecloud/restapi/v2.1
Latest version:
http://wirecloud.github.io/wirecloud/restapi/latest

Editors

Copyright © 2012-2017 by Universidad Politécnica de Madrid

License

This specification is licensed under the FIWARE Open Specification License (implicit patents license).


Abstract

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 document) is a RESTful one.

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 at the Application Mashup server for building these workspaces.

This document also show some examples that can be tested using WireCloud, the reference implementation of the FIWARE Application Mashup GE.

Status of this document

This is a work in progress and is changing on a daily basis. You can check the latest available version on: https://github.com/Wirecloud/wirecloud/tree/develop. Please send your comments to wirecloud@conwet.com


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

WireCloud provides support for Cookie and OAuth2 authentication being OAuth2 the default in FIWARE Lab.

Representation Format

The Application Mashup API MUST support at least JSON for delivering any kind of resources. It may also support other formats as simple text, XML and HTML. 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.

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 (through the description attribute) for displaying to end users. If the server can provide extra details about the error, they will be provided through the details attribute.

JSON Example:

{
    "description": "Missing dependencies",
    "details": {
       "missingDependencies": [
           "Wirecloud/nonavailable-operator/1.0",
           "Wirecloud/nonavailable-widget/1.0"
       ]
    }
}

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>

HTTP Verbs

Where possible, this API strives to use appropriate HTTP verbs for each action.

Verb Description
HEAD Can be issued against any resource to get just the HTTP header info associated with the GET response.
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for replacing resources.
DELETE Used for deleting resources.
PATCH Used for updating resources with partial JSON data (using the application/json-patch+json mimetype). For instance, a Workspace resource has several attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.

Any API endpoint supporting the GET method must also support the HEAD method.

Used HTTP Status Codes

HTTP Code Type Description
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.
405 Method Not Allowed The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics 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 already taken name.
413 Request Entity Too Large The request is larger than the server is willing or able to process.
415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
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.

API Specification

Core

Supported features

[/api/features]

List all supported features

GET /api/features

Used status codes: 200, 304, 406

NOTE: This action SHOULD NOT be protected by any authentication mechanism.

Platform preferences

[/api/preferences/platform]

Retrieve platform preferences

GET /api/preferences/platform

Used status codes: 200, 304, 401, 403, 406

Update platform preferences

POST /api/preferences/platform

Used status codes: 204, 400, 401, 403, 413, 415

Managing workspaces

Workspace collection

[/api/workspaces]

List workspaces

GET /api/workspaces

List all the workspaces available to the user. If the request is made without including user credentials, this action will return all the public workspaces.

This action will return a subset of the fields returned by the Get workspace details action. More specifically, this API will return the following fields: description, id, lastmodified, longdescription, name, owner, removable and shared.

Used status codes: 200, 304, 401, 406

Create new workspaces

POST /api/workspaces

Creates a new workspace. This workspace will be empty, created from a template or created by duplicating an existing workspace depending on the used parameters.

Those parameters should be sent in the body of the request using the selected representation format (e.g. JSON):

  • 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): Id for the new workspace. This parameter is optional if either mashup or workspace are used. In those cases, the name parameter will be obtained from the referenced mashup or workspace. This parameter is also optional if the title is provided, in this case a urlify version of the title parameter will be used as name. This parameter currently support any character (except '/'), but it is recommended to only use english alphanumeric characters (lowercase), dashes ('-') and underscores ('_') as this parameter will be used in URLs. Moreover, future versions of the API will enforce this.

  • title (string): Title for the new workspace. This parameter is optional. If either mashup or workspace are used, the title parameter will be obtained from the referenced mashup or workspace. In any other case it will be filled using the name parameter.

  • allow_renaming (boolean; default: false): If false, any attempt to create a workspace using a currently used name will fail (with a 409 status code). If this parameter is true and the name is already in use, a new name will be computed using the indicated name as base.

If everything goes well and the workspace is created, this action will return the initial workspace details using the same format used in the Get workspace details action.

Used status codes: 201, 400, 401, 403, 406, 409, 413, 415, 422

Workspace

[/api/workspace/{workspace_id}]
Parameters
workspace_id (required, number)

ID of the workspace

Get workspace details

GET /api/workspace/{workspace_id}

Returned fields:

  • id (string): Id of the workspace.

  • owner (string): Username of the workspace's owner.

  • name (string): Name of the workspace.

  • title (string, available in WireCloud 1.1+ / FIWARE Application Mashup RESTful Specification v2.2+): Title of the workspace.

  • description (string, available in WireCloud 1.0+ / FIWARE Application Mashup RESTful Specification v2.1+): Short description in plain text describing the workspace.

  • longdescription (string, available in WireCloud 1.0+ / FIWARE Application Mashup RESTful Specification v2.1+): Text describing this workspace. This field can be formatted using Markdown.

  • preferences (object): Preference values.

  • lastmodified (number): Unix timestamp indicating the last time this workspace was updated.

  • tabs (array): Visual description of the workspace.

  • wiring (object): Wiring configuration of the workspace. See the Update workspace wiring configuration action documentation for more details about the structure of this field.

  • removable (object): Indicates wheter this workspace can be removed by the current user.

  • users (object): List of users and groups with access to this workspace.

  • shared (boolean): Indicates whether this workspace has been shared with other users or groups.

Used status codes: 200, 401, 403, 404, 406

Update workspace details

POST /api/workspace/{workspace_id}

Workspace attributes that can be modified:

  • name (string): Name of the workspace. This parameter currently support any character (except '/'), but it is recommended to only use english alphanumeric characters (lowercase), dashes ('-') and underscores ('_') as this parameter will be used in URLs. Moreover, future versions of the API will enforce this.

  • title (string, available in WireCloud 1.1+ / FIWARE Application Mashup RESTful Specification v2.2+): Title of the workspace.

  • description (string, available in WireCloud 1.0+ / FIWARE Application Mashup RESTful Specification v2.1+): Short description in plain text describing the workspace.

  • longdescription (string, available in WireCloud 1.0+ / FIWARE Application Mashup RESTful Specification v2.1+): Text describing this workspace. This field can be formatted using Markdown.

Used status codes: 204, 400, 401, 403, 404, 415

Update workspace preferences

POST /api/workspace/{workspace_id}/preferences

Used status codes: 204, 400, 401, 403, 404, 413, 415

NOTE: Supported preferences varies depending on the extensions enabled on the Application Mashup instance.

Parameters
workspace_id (required, number)

ID of the workspace

Patch workspace wiring configuration

PATCH /api/workspace/{workspace_id}/wiring
  • version (string): Format version used in this wiring configuration. At present, the only available version is "2.0".

  • operators (object): Description of the operators used in this wiring description.

  • connections (array): Connections stablished between widgets and operators.

  • visualdescription (object): Visual description. Used for displaying this wiring configuration in the user interface.

Used status codes: 204, 400, 401, 403, 404, 413, 422

new in WireCloud 1.1 / FIWARE Application Mashup RESTful Specification v2.2

Parameters
workspace_id (required, number)

ID of the workspace

Update workspace wiring configuration

PUT /api/workspace/{workspace_id}/wiring
  • version (string): Format version used in this wiring configuration. At present, the only available version is "2.0".

  • operators (object): Description of the operators used in this wiring description.

  • connections (array): Connections stablished between widgets and operators.

  • visualdescription (object): Visual description. Used for displaying this wiring configuration in the user interface.

Used status codes: 204, 400, 401, 403, 404, 413, 422

Parameters
workspace_id (required, number)

ID of the workspace

Delete workspace

DELETE /api/workspace/{workspace_id}

Used status codes: 204, 401, 403, 404

Adding new tabs

POST /api/worksace/{workspace_id}/tabs

Creates a new empty tab. This request must provide the name or the title parameter to be used for creating the tab in the body of the request using the selected representation format (e.g. JSON).

Used status codes: 201, 400, 401, 403, 404, 406, 413, 415, 422

Tab

[/api/workspace/{workspace_id}/tab/{tab_id}]
Parameters
tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Get tab details

GET /api/workspace/{workspace_id}/tab/{tab_id}

Returned fields:

  • id (string): Id of the tab.

  • name (string): Name of the tab.

  • title (string, available in WireCloud 1.1+ / FIWARE Application Mashup RESTful Specification v2.2+): Title of the tab.

  • visible (boolean): Indicates if this is the tab to display by default when loading the workspace.

  • iwidgets (array): List of widgets associated with this tab.

  • preferences (object): Preference values.

Used status codes: 200, 401, 403, 404, 406, 413, 415, 422

new in WireCloud 1.0 / FIWARE Application Mashup RESTful Specification v2.1

Update tab details

POST /api/workspace/{workspace_id}/tab/{tab_id}

Tab attributes that can be modified:

  • name (string): Name to use for identifying this tab. This parameter currently support any character (except '/'), but it is recommended to only use english alphanumeric characters (lowercase), dashes ('-') and underscores ('_') as this parameter will be used in URLs. Moreover, future versions of the API will enforce this.

  • title (string, available in WireCloud 1.1+ / FIWARE Application Mashup RESTful Specification v2.2+): Label to display in the user interface.

  • visible (boolean): true to make this the initial/default tab of the workspace.

Used status codes: 204, 400, 401, 403, 404, 409, 413, 415, 422

NOTE: WireCloud versions prior to 1.0 implemented incorrectly this endpoint by using PUT requests instead of using POST requests.

Update tab preferences

POST /api/workspace/{workspace_id}/tab/{tab_id}/preferences

Used status codes: 204, 400, 401, 403, 404, 413, 415

NOTE: Supported preferences varies depending on the extensions enabled on the Application Mashup instance.

Parameters
tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Delete a tab

DELETE /api/workspace/{workspace_id}/tab/{tab_id}

Used status codes: 204, 401, 403, 404

Add new widgets

POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidgets

Adds a widget to the workspace/tab. This request support the following parameters (that should be send in the body of the request using the selected representation format, e.g. JSON):

  • widget (string): Id (vendor/name/version) of the widget to instantiate.

  • title (optional, string): Title of the widget. If not provided, the title of the widget will be obtained from the widget description (config.xml).

Used status codes: 201, 400, 401, 403, 404, 406, 413, 415, 422

Parameters
tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Instantiated widget

[/api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}]
Parameters
iwidget_id (required, number)

ID of the instantiated widget

tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Update instantiated widget details

POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}

Updates the attributes of a instantiated widget. Only the attributes referenced in the request will be updated leaving the other attributes intact. The modificable attributes are:

  • title (string): Title for the 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): Width of the widget in layout columns.

  • height (number): Height of the widget in layout rows.

  • top (number): Vertical position of the widget in layout rows.

  • left (number): Horizontal postiion of the widget in layout columns.

  • zIndex (number): Stack order of the widget.

Used status codes: 204, 400, 401, 403, 404, 413, 415, 422

Get instantiated widget preferences

GET /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/preferences

new in WireCloud 1.1 / FIWARE Application Mashup RESTful Specification v2.2

Used status codes: 200, 304, 401, 403

Parameters
iwidget_id (required, number)

ID of the instantiated widget

tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Update instantiated widget preferences

POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/preferences

Used status codes: 204, 400, 401, 403, 404, 413, 415

Parameters
iwidget_id (required, number)

ID of the instantiated widget

tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Get instantiated widget properties

GET /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/properties

new in WireCloud 1.1 / FIWARE Application Mashup RESTful Specification v2.2

Used status codes: 200, 304, 401, 403

Parameters
iwidget_id (required, number)

ID of the instantiated widget

tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Update instantiated widget properties

POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/properties

Used status codes: 204, 400, 401, 403, 404, 413, 415

Parameters
iwidget_id (required, number)

ID of the instantiated widget

tab_id (required, number)

ID of the tab

workspace_id (required, number)

ID of the workspace

Remove instantiated widget

DELETE /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}

Used status codes: 204, 401, 403, 404

Operator variables

[/api/workspace/{workspace_id}/operators/{operator_id}/variables]
Parameters
operator_id (required, number)

ID of the operator

workspace_id (required, number)

ID of the workspace

Get operator variables

GET /api/workspace/{workspace_id}/operators/{operator_id}/variables

new in WireCloud 1.1 / FIWARE Application Mashup RESTful Specification v2.2

Used status codes: 200, 304, 401, 403

Managing resources

Resource collection

[/api/resources]

List available Mashable Application Components

GET /api/resources

Used status codes: 200, 401, 406

 Upload Mashable Application Components

POST /api/resources

Due to this request handles binary content, this request SHOULD support the following extra Content-Types for the request itself: application/octect-stream and multipart/form-data.

Used status codes: 204, 401, 403, 404, 406, 409, 413, 415

Resource

[/api/resource/{vendor}/{name}/{version}]
Parameters
name (required, string)

Name ID of the Mashable Application Component

vendor (required, string)

ID of the Mashable Application Component

version (required, string)

Version of the Mashable Application Component

Export Mashable Application Component

GET /api/resource/{vendor}/{name}/{version}

Used status codes: 200, 401, 403, 404, 406

Uninstall all versions of a Mashable Application Component

DELETE /api/resource/{vendor}/{name}

Used status codes: 204, 401, 403, 404

Parameters
name (required, string)

Name ID of the Mashable Application Component

vendor (required, string)

ID of the Mashable Application Component

Uninstall Mashable Application Component

DELETE /api/resource/{vendor}/{name}/{version}

Used status codes: 204, 401, 403, 404

Examples

Core

Supported features

[/api/features]
List all supported features
GET /api/features
Request /api/features

Headers

Accept: application/json
Response 200

Body

{
    "FIWARE": "5.2.1",
    "Wirecloud": "0.9.0",
    "ObjectStorage": "0.5",
    "ApplicationMashup": "1.0",
    "NGSI": "1.0",
    "FullscreenWidget": "0.5",
    "StyledElements": "0.5"
}

Platform preferences

[/api/preferences/platform]
Retrieve platform preferences
GET /api/preferences/platform
Request /api/preferences/platform

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
    "language": {
        "value": "en-gb",
        "inherit": false
    }
}
Update platform preferences
POST /api/preferences/platform
Request /api/preferences/platform (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "language": {
        "value": "browser"
    }
}
Response 204

Managing workspaces

Workspace collection

[/api/workspaces]
List workspaces
GET /api/workspaces
Request List available workspaces /api/workspaces

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

[
    {
        "description": "My dashboard",
        "id": "1",
        "lastmodified": 1464187437041,
        "longdescription": "",
        "name": "workspace",
        "owner": "user",
        "removable": true,
        "shared": false,
        "title": "Workspace"
    },
    {
        "description": "A public dashboard",
        "id": "20",
        "lastmodified": 1461673370860,
        "longdescription": "A dashboard description using **Markdown** _Syntax_",
        "name": "public-workspace",
        "owner": "otheruser",
        "removable": false,
        "shared": true,
        "title": "Public Workspace"
    }
]
Response 200 (application/json)

Headers

Content-Type: application/json

Body

[
    {
        "description": "A public dashboard",
        "id": "20",
        "lastmodified": 1461673370860,
        "longdescription": "A dashboard description using **Markdown** _Syntax_",
        "name": "public-workspace",
        "owner": "otheruser",
        "removable": false,
        "shared": true,
        "title": "Public Workspace"
    }
]
Request List public workspaces /api/workspaces

Headers

Accept: application/json
Response 200 (application/json)

Headers

Content-Type: application/json

Body

[
    {
        "description": "A public dashboard",
        "id": "20",
        "lastmodified": 1461673370860,
        "longdescription": "A dashboard description using **Markdown** _Syntax_",
        "name": "public-workspace",
        "owner": "otheruser",
        "removable": false,
        "shared": true,
        "title": "Public Workspace"
    }
]
Create new workspaces
POST /api/workspaces
Request Empty workspace /api/workspaces (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "name": "test"
}
Response 201 (application/json)

Headers

Content-Type: application/json

Body

{
    "description": "",
    "empty_params": [],
    "extra_prefs": {},
    "id": "81",
    "lastmodified": 1464187437041,
    "longdescription": "",
    "name": "test",
    "owner": "admin",
    "preferences": {
        "public": {"value": "true", "inherit": false}
    },
    "removable": true,
    "shared": false,
    "tabs": [
        {
            "visible": true,
            "iwidgets": [],
            "id": "84",
            "name": "tab",
            "preferences": {},
            "title": "Tab"
        }
    ],
    "title": "test",
    "users": [],
    "wiring": {"operators": {}, "connections": []}
}
Request Workspace from mashup /api/workspaces (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "mashup": "UPM/Mashup/1.0"
}
Response 201 (application/json)

Headers

Content-Type: application/json

Body

{
    "description": "",
    "empty_params": [],
    "extra_prefs": {},
    "id": "50",
    "lastmodified": 1464187437041,
    "longdescription": "",
    "name": "example",
    "owner": "admin",
    "preferences": {},
    "removable": true,
    "shared": false,
    "tabs": [
        {
            "visible": true,
            "iwidgets": [
                {
                    "widget": "UPM/Widget1/0.1",
                    "layout": 0,
                    "title": "Widget1",
                    "icon_top": -1,
                    "variables": {},
                    "minimized": false,
                    "id": "311",
                    "height": 28,
                    "zIndex": 0,
                    "width": 6,
                    "readOnly": false,
                    "icon_left": -1,
                    "top": 0,
                    "fulldragboard": false,
                    "left": 0
                },
                {
                    "widget": "UPM/Widget2/0.1",
                    "layout": 0,
                    "title": "Widget2",
                    "icon_top": -1,
                    "variables": {},
                    "minimized": false,
                    "id": "312",
                    "height": 28,
                    "zIndex": 0,
                    "width": 6,
                    "readOnly": false,
                    "icon_left": -1,
                    "top": 0,
                    "fulldragboard": false,
                    "left": 7
                }
            ],
            "id": "100",
            "name": "tab",
            "preferences": {},
            "title": "Tab"
        }
    ],
    "title": "Example",
    "users": [],
    "wiring": {"operators": {}, "connections": []},
}
Request Workspace from inexistent mashup /api/workspaces (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "mashup": "UPM/inexistent-mashup/1.0"
}
Response 422 (application/json)

Headers

Content-Type: application/json

Body

{
    "description": "Mashup not found: UPM/inexistent-mashup/1.0"
}
Request Workspace using an invalid mashup id /api/workspaces (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "mashup": "invalid id"
}
Response 422 (application/json)

Headers

Content-Type: application/json

Body

{
    "description": "invalid mashup id"
}
Request Duplicating a workspace /api/workspaces (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "workspace": "81"
}
Response 201 (application/json)

Headers

Content-Type: application/json

Body

{
    "description": "",
    "empty_params": [],
    "extra_prefs": {},
    "id": "200",
    "lastmodified": 1464207200516,
    "longdescription": "",
    "name": "example",
    "owner": "admin",
    "preferences": {},
    "removable": true,
    "shared": false,
    "tabs": [
        {
            "visible": true,
            "iwidgets": [
                {
                    "widget": "UPM/Widget1/0.1",
                    "layout": 0,
                    "title": "Widget1",
                    "icon_top": -1,
                    "variables": {},
                    "minimized": false,
                    "id": "313",
                    "height": 28,
                    "zIndex": 0,
                    "width": 6,
                    "readOnly": false,
                    "icon_left": -1,
                    "top": 0,
                    "fulldragboard": false,
                    "left": 0
                },
                {
                    "widget": "UPM/Widget2/0.1",
                    "layout": 0,
                    "title": "Widget2",
                    "icon_top": -1,
                    "variables": {},
                    "minimized": false,
                    "id": "314",
                    "height": 28,
                    "zIndex": 0,
                    "width": 6,
                    "readOnly": false,
                    "icon_left": -1,
                    "top": 0,
                    "fulldragboard": false,
                    "left": 7
                }
            ],
            "id": "101",
            "name": "tab",
            "preferences": {},
            "name": "Tab"
        }
    ],
    "title": "Example",
    "users": [],
    "wiring": {"operators": {}, "connections": []}
}

Workspace

[/api/workspace/{workspace_id}]
Get workspace details
GET /api/workspace/{workspace_id}
Request /api/workspace/81

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200

Body

{
    "description": "",
    "empty_params": [],
    "extra_prefs": {},
    "id": 81,
    "lastmodified": 1464207200516,
    "longdescription": "A dashboard description using **Markdown** _Syntax_",
    "name": "test",
    "owner": "admin",
    "preferences": {},
    "removable": true,
    "shared": false,
    "tabs": [
        {
            "visible": true,
            "iwidgets": [],
            "id": 84,
            "name": "tab",
            "preferences": {},
            "title": "Tab"
        }
    ],
    "title": "Test",
    "users": [
        {
            "accesslevel": "read",
            "fullname": "Full Name"
            "organization": false,
            "username": "test"
        },
        {
            "accesslevel": "read",
            "fullname": "WireCloud"
            "organization": true,
            "username": "wirecloud"
        }
    ],
    "wiring": {"operators": {}, "connections": []}
}
Update workspace details
POST /api/workspace/{workspace_id}
Request /api/workspace/81 (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "title": "New Name",
    "name": "new-name",
    "longdescription": "A dashboard description using **Markdown** _Syntax_"
}
Response 204

Update workspace preferences
POST /api/workspace/{workspace_id}/preferences
Request /api/workspace/81/preferences (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "public": {"value": "true"}
}
Response 204

Patch workspace wiring configuration
PATCH /api/workspace/{workspace_id}/wiring
Request Replace a preference and add an operator /api/workspace/81/wiring (application/json-patch+json)

Headers

Content-Type: application/json-patch+json
Accept: application/json-patch+json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

    [
        {
            "op": "replace",
            "path": "/operators/1/preferences/preferenceName/value",
            "value": "newPreferenceValue",
        },
        {
            "op": "add",
            "path": "/operators/0/",
            "value": {
                "name": "UPM/Operator/0.1",
                "id": "0"
            },
        }
    ]
Response 204

Request Remove operator /api/workspace/81/wiring

Headers

Accept: application/json-patch+json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

    [
        {
            "op": "remove",
            "path": "/operators/1",
        }
    ]
Response 204

Update workspace wiring configuration
PUT /api/workspace/{workspace_id}/wiring
Request /api/workspace/81/wiring (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
   "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"
         }
      }
   ]
}
Response 204

Delete workspace
DELETE /api/workspace/{workspace_id}
Request /api/workspace/81

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 204

Adding new tabs
POST /api/worksace/{workspace_id}/tabs
Request /api/worksace/81/tabs (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "title": "Tab 2"
}
Response 201 (application/json)

Headers

Content-Type: application/json

Body

{
   "id": "3",
   "iwidgets": [],
   "name": "tab-2",
   "preferences": {},
   "title": "Tab 2",
   "visible": false
}

Tab

[/api/workspace/{workspace_id}/tab/{tab_id}]
Get tab details
GET /api/workspace/{workspace_id}/tab/{tab_id}
Request /api/workspace/81/tab/100

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200

Body

{
    "id": "84",
    "iwidgets": [
        {
            "widget": "UPM/Widget1/0.1",
            "layout": 0,
            "title": "Widget1",
            "icon_top": -1,
            "variables": {},
            "minimized": false,
            "id": "313",
            "height": 28,
            "zIndex": 0,
            "width": 6,
            "readOnly": false,
            "icon_left": -1,
            "top": 0,
            "fulldragboard": false,
            "left": 0
        },
        {
            "widget": "UPM/Widget2/0.1",
            "layout": 0,
            "title": "Widget2",
            "icon_top": -1,
            "variables": {},
            "minimized": false,
            "id": "314",
            "height": 28,
            "zIndex": 0,
            "width": 6,
            "readOnly": false,
            "icon_left": -1,
            "top": 0,
            "fulldragboard": false,
            "left": 7
        }
    ],
    "name": "Tab",
    "preferences": {},
    "title": "tab",
    "visible": true
}
Update tab details
POST /api/workspace/{workspace_id}/tab/{tab_id}
Request /api/workspace/81/tab/100 (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "name": "new-name",
    "title": "New Name"
}
Response 204

Update tab preferences
POST /api/workspace/{workspace_id}/tab/{tab_id}/preferences
Request /api/workspace/81/tab/100/preferences (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "baselayout": {
        "inherit": false,
        "value": "{\"verticalmargin\":3,\"smart\":\"false\",\"horizontalmargin\":4,\"type\":\"gridlayout\",\"columns\":20,\"cellheight\":12,\"rows\":12}"
    }
}
Response 204

Delete a tab
DELETE /api/workspace/{workspace_id}/tab/{tab_id}
Request /api/workspace/81/tab/100

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 204

Add new widgets
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidgets
Request /api/workspace/81/tab/100/iwidgets (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

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

Body

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

Instantiated widget

[/api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}]
Update instantiated widget details
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}
Request /api/workspace/81/tab/100/iwidget/101 (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "title": "new title"
}
Response 204

Get instantiated widget preferences
GET /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/preferences
Request /api/workspace/81/tab/100/iwidget/101/preferences

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
    "first_preference_name": {
        "readonly": false,
        "hidden": false,
        "name": "boolean",
        "value": false,
        "secure": false
    },
    "second_preference_nanme": {
        "readonly": false,
        "hidden": false,
        "name": "text",
        "value": "initial text",
        "secure": false
    }
}
Update instantiated widget preferences
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/preferences
Request /api/workspace/81/tab/100/iwidget/101/preferences (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "pref": "value"
}
Response 204

Get instantiated widget properties
GET /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/properties
Request /api/workspace/81/tab/100/iwidget/101/properties

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
    "first_property_name": {
        "readonly": false,
        "hidden": false,
        "name": "boolean",
        "value": false,
        "secure": false
    },
    "second_property_nanme":
    {
        "readonly": false,
        "hidden": false,
        "name": "text",
        "value": "initial text",
        "secure": false
    }
}
Update instantiated widget properties
POST /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}/properties
Request /api/workspace/81/tab/100/iwidget/101/properties (application/json)

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

{
    "property_name": "new_value"
}
Response 204

Remove instantiated widget
DELETE /api/workspace/{workspace_id}/tab/{tab_id}/iwidget/{iwidget_id}
Request /api/workspace/81/tab/100/iwidget/101

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 204

Operator variables

[/api/workspace/{workspace_id}/operators/{operator_id}/variables]
Get operator variables
GET /api/workspace/{workspace_id}/operators/{operator_id}/variables
Request /api/workspace/81/operators/101/variables

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
    "preferences": {
        "username":
        {
            "hidden": false,
            "name": "username",
            "readonly": false,
            "secure": false,
            "value": "test_username"
        },
        "password":
        {
            "hidden": false,
            "name": "password",
            "readonly": false,
            "secure": true,
            "value": "********"
        }
    }
}

Managing resources

Resource collection

[/api/resources]
List available Mashable Application Components
GET /api/resources
Request /api/resources

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
   "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.",
        "preferences": [
            {
                "default": "http://orion.lab.fiware.org:1026/",
                "description": "URL of the Orion Context Broker to use for retrieving entity information"
                "label": "NGSI server URL"
                "name": "ngsi_server"
                "readonly": false
                "secure": false
                "type": "text"
                "value": null
            }
        ],
        "wiring": {
            "inputs": [],
            "outputs": []
        }
   },
   "UPM/Operator/1.0": {
        "type": "operator",
        "vendor": "UPM",
        "name": "Operator"
        "version": "1.0",
        "description": "Example operator",
        "preferences": [],
        "wiring": {
            "inputs": [],
            "outputs": []
        }
   }
}
 Upload Mashable Application Components
POST /api/resources
Request /api/resources (application/octet-stream)

Headers

Content-Type: application/octet-stream
Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN

Body

‹Binary data (Not supported on APIary)›
Response 201 (application/json)

Headers

Content-Type: application/json

Body

{
    "contributors": [],
    "image": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/images/catalogue.png",
    "type": "widget",
    "smartphoneimage": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/images/catalogue_iphone.png",
    "contents": {
        "src": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/test.html",
        "charset": "utf-8",
        "contenttype": "text/html",
        "cacheable": true,
        "useplatformstyle": false
    },
    "requirements": [],
    "preferences": [
        {
            "secure": false,
            "description": "list preference",
            "default": "default",
            "value": null,
            "label": "list",
            "readonly": false,
            "type": "list",
            "options": [
                {
                    "value": "default",
                    "label": "Default"
                },
                {
                    "value": "1",
                    "label": "value1"
                },
                {
                    "value": "2",
                    "label": "value2"
                }
            ],
            "name": "list"
        },
        {
            "secure": false,
            "description": "text preference",
            "default": "initial text",
            "value": null,
            "label": "text",
            "readonly": false,
            "type": "text",
            "name": "text"
        },
        {
            "secure": false,
            "description": "boolean preference",
            "default": "false",
            "value": null,
            "label": "boolean",
            "readonly": false,
            "type": "boolean",
            "name": "boolean"
        },
        {
            "secure": false,
            "description": "password preference",
            "default": "default",
            "value": null,
            "label": "password",
            "readonly": false,
            "type": "password",
            "name": "password"
        },
        {
            "secure": false,
            "description": "number preference",
            "default": "2",
            "value": null,
            "label": "number",
            "readonly": false,
            "type": "number",
            "name": "number"
        }
    ],
    "title": "Test",
    "wiring": {
        "inputs": [
            {
                "friendcode": "test-data",
                "name": "inputendpoint",
                "actionlabel": "",
                "label": "Input",
                "type": "text",
                "description": ""
            },
            {
                "friendcode": "nothandled",
                "name": "nothandled",
                "actionlabel": "",
                "label": "Not handled endpoint",
                "type": "text",
                "description": ""
            }
        ],
        "outputs": [
            {
                "description": "",
                "type": "text",
                "friendcode": "test-data",
                "name": "outputendpoint",
                "label": "Output"
            }
        ]
    },
    "longdescription": "DESCRIPTION.md",
    "version": "1.0",
    "widget_height": "24",
    "homepage": "",
    "email": "aarranz@conwet.com",
    "default_lang": "en",
    "issuetracker": "",
    "vendor": "Wirecloud",
    "description": "This widget is used to test some of the features of the Wirecloud platform",
    "authors": [
        {
            "name": "aarranz"
        }
    ],
    "properties": [],
    "altcontents": [],
    "name": "Test",
    "license": "",
    "changelog": "CHANGELOG.md",
    "doc": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/doc/index.md",
    "licenseurl": "",
    "widget_width": "6"
}
Request Multipart /api/resources (multipart/form-data; boundary=----WebKitFormBoundaryHPwaOXLATyUcGQp8)

Headers

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryHPwaOXLATyUcGQp8

Body

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

‹Base64 data›

------WebKitFormBoundaryHPwaOXLATyUcGQp8--
Response 201 (application/json)

Headers

Content-Type: application/json

Body

{
    "contributors": [],
    "image": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/images/catalogue.png",
    "type": "widget",
    "smartphoneimage": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/images/catalogue_iphone.png",
    "contents": {
        "src": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/test.html",
        "charset": "utf-8",
        "contenttype": "text/html",
        "cacheable": true,
        "useplatformstyle": false
    },
    "requirements": [],
    "preferences": [
        {
            "secure": false,
            "description": "list preference",
            "default": "default",
            "value": null,
            "label": "list",
            "readonly": false,
            "type": "list",
            "options": [
                {
                    "value": "default",
                    "label": "Default"
                },
                {
                    "value": "1",
                    "label": "value1"
                },
                {
                    "value": "2",
                    "label": "value2"
                }
            ],
            "name": "list"
        },
        {
            "secure": false,
            "description": "text preference",
            "default": "initial text",
            "value": null,
            "label": "text",
            "readonly": false,
            "type": "text",
            "name": "text"
        },
        {
            "secure": false,
            "description": "boolean preference",
            "default": "false",
            "value": null,
            "label": "boolean",
            "readonly": false,
            "type": "boolean",
            "name": "boolean"
        },
        {
            "secure": false,
            "description": "password preference",
            "default": "default",
            "value": null,
            "label": "password",
            "readonly": false,
            "type": "password",
            "name": "password"
        },
        {
            "secure": false,
            "description": "number preference",
            "default": "2",
            "value": null,
            "label": "number",
            "readonly": false,
            "type": "number",
            "name": "number"
        }
    ],
    "title": "Test",
    "wiring": {
        "inputs": [
            {
                "friendcode": "test-data",
                "name": "inputendpoint",
                "actionlabel": "",
                "label": "Input",
                "type": "text",
                "description": ""
            },
            {
                "friendcode": "nothandled",
                "name": "nothandled",
                "actionlabel": "",
                "label": "Not handled endpoint",
                "type": "text",
                "description": ""
            }
        ],
        "outputs": [
            {
                "description": "",
                "type": "text",
                "friendcode": "test-data",
                "name": "outputendpoint",
                "label": "Output"
            }
        ]
    },
    "longdescription": "DESCRIPTION.md",
    "version": "1.0",
    "widget_height": "24",
    "homepage": "",
    "email": "aarranz@conwet.com",
    "default_lang": "en",
    "issuetracker": "",
    "vendor": "Wirecloud",
    "description": "This widget is used to test some of the features of the Wirecloud platform",
    "authors": [
        {
            "name": "aarranz"
        }
    ],
    "properties": [],
    "altcontents": [],
    "name": "Test",
    "license": "",
    "changelog": "CHANGELOG.md",
    "doc": "https://mashup.lab.fiware.org/catalogue/media/Wirecloud/Test/1.0/doc/index.md",
    "licenseurl": "",
    "widget_width": "6"
}

Resource

[/api/resource/{vendor}/{name}/{version}]
Export Mashable Application Component
GET /api/resource/{vendor}/{name}/{version}
Request /api/resource/Wirecloud/Test/0.9

Headers

Accept: */*
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 200 (application/octet-stream)

Headers

Content-Type: application/octet-stream

Body

‹Binary data (Not supported on APIary)›
Uninstall all versions of a Mashable Application Component
DELETE /api/resource/{vendor}/{name}
Request /api/resource/Wirecloud/Test

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 204

Uninstall Mashable Application Component
DELETE /api/resource/{vendor}/{name}/{version}
Request /api/resource/Wirecloud/Test/0.9

Headers

Accept: application/json
Authorization: Bearer YOUR_OAUTH2_TOKEN
Response 204

Acknowledgements

The editors would like to express their gratitude to the following people who actively contributed to this specification: Aitor Magan and Francisco de la Vega

References