<commit_before>FORMAT: 1A
HOST: https://mashup.lab.fiware.org/
TITLE: FIWARE Application Mashup RESTful v2 Specification
DATE: 30 September 2015
VERSION: v2
PREVIOUS_VERSION: v1
APIARY_PROJECT: fiwareapplicationmashup

# FIWARE Application Mashup RESTful Specification

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. You
can find the Widget API in this separate [entry](https://github.com/Wirecloud/wirecloud/tree/develop/docs/widgetapi/widgetapi.md).

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.


## Editors

  + <NAME>, Universidad Politécnica de Madrid

## Acknowledgements

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

## Status

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 <EMAIL>

This specification is licensed under the [FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29).

## Copyright

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

## 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>

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

# Group Core

## Supported features [/api/features]

### List all supported features [GET]

**Used status codes**: 200, 304, 406

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

+ Request

    + 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]

### Retrieve platform preferences [GET]

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

+ Request

    + Headers<commit_msg>API documentation: Fix platform preferences API endpoint<commit_after>FORMAT: 1A
HOST: https://mashup.lab.fiware.org/
TITLE: FIWARE Application Mashup RESTful v2 Specification
DATE: 30 September 2015
VERSION: v2
PREVIOUS_VERSION: v1
APIARY_PROJECT: fiwareapplicationmashup

# FIWARE Application Mashup RESTful Specification

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. You
can find the Widget API in this separate [entry](https://github.com/Wirecloud/wirecloud/tree/develop/docs/widgetapi/widgetapi.md).

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.


## Editors

  + <NAME>, Universidad Politécnica de Madrid

## Acknowledgements

The editors would like to express their gratitude to the following people who actively contributed to this specification:
<NAME> and <NAME>

## Status

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 <EMAIL>

This specification is licensed under the [FIWARE Open Specification License (implicit patents license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29).

## Copyright

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

## 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>

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

# Group Core

## Supported features [/api/features]

### List all supported features [GET]

**Used status codes**: 200, 304, 406

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

+ Request

    + 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]

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

+ Request

    + Headers
{'fraction_non_alphanumeric': 0.07243770870793732, 'fraction_numerical': 0.01618289237092217, 'mean_word_length': 2.8178475116450112, 'pattern_counts': {'":': 20, '<': 36, '<?xml version=': 2, '>': 38, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7040322', 'n_tokens_mistral': 3846, 'n_tokens_neox': 3539, 'n_words': 1818}