Federation

Version: 0.1.0-development

This document described the Federation API, which must be used to federate assets to the OrganiCity Platform.

This API can only be called by clients with the prefix ocsite-, e.g. ocsite-santander or ocsite-london.

The Federation API is implmented by the OC Proxy.

A tutorial can be found here.

Schemes: https

Base URL: https://dev.orion.organicity.eu/v2/

Summary

Security

Bearer

name:
Authorization
in:
header
description:
Every API call must be authorized with a Bearer Token in the HTTP header (Authorization: Bearer <TOKEN>) provided by OrganiCity Accounts - https://accounts.organicity.eu

Paths

POST /entities

Role ocsite required.

This endpoint must be used to push (e.g. create) new assets into the OC Platform.

application/json

The HTTP body is an asset to be pushed to the OC Platform in JSON format as described here.

asset

Reference: AssetCreation
fiware-service

The API must be called withe HTTP header fiware-service:organicity.

header string
201 Created

An asset was created successfully. The location header will be set with Location: /v2/entities/{assetId}.

An example:

/v2/entities/urn:oc:entity:experimenters:cf2c1723-3369-4123-8b32-49abe71c0e57:57e127c010590cb31ca82aa4:1?type=urn:oc:entityType:demo

400 Bad Request

An error occured. Examples:

Example for application/json
{
"description": "No HTTP body provided.",
"error": "InternalServerError"
}
Reference: Error
422 Unprocessable Entity

This error will be thrown, if the asset with the given id inside the asset already exists.

Example for application/json
{
"description": "Already Exists",
"error": "Unprocessable"
}
Reference: Error
Bearer

DELETE /entities/{assetId}

Role ocsite required.

This endpoint must be used to delete an asset from the OC Platform.

assetId

The identifier of the asset

path string
204 No Content

An empty response sais, that the asset was deleted successfully.

404 Not Found

The asset with the given assetId does not exists.

Example for application/json
{
"description": "The requested entity has not been found. Check type and id",
"error": "NotFound"
}
Reference: Error
Bearer

POST /entities/{assetId}/attrs

Role ocsite required.

This endpoint must be used to update an asset into the OC Platform.

The HTTP body is an asset to be updated to the OC Platform in JSON format as described here.

In case of an update, the attributes id and type are not allowed!

asset

Reference: AssetUpdate
fiware-service

The API must be called withe HTTP header fiware-service:organicity.

header string
assetId

The identifier of the asset

path string
204 No Content

An empty response sais, that the asset was updated successfully.

400 Bad Request

An error occured. Examples:

Example for application/json
{
"description": "No HTTP body provided.",
"error": "InternalServerError"
}
Reference: Error
404 Not Found

The asset with the given assetId does not exists.

Example for application/json
{
"description": "The requested entity has not been found. Check type and id",
"error": "NotFound"
}
Reference: Error
Bearer

Schema definitions

AssetCreation: object

This JSON object represents an asset, if it is created. The minimal required attrbutes are id, type and TimeInstant.

id: string

Each entity must have an unique identifier (IDs) in the form of

urn:oc:entity:[site]:[service]:[provider]:[group]:[entityName]

where:

  • urn:oc:entity:[site]:[service]:[provider]:[group]:[entityName] must be unique across the whole OC Facility.
  • [site] is representing the federated OC Site (e.g., London, Santander, Aarhus, Experimenters etc.). During the creation of your experiment you are going to acquire the proper prefixes for your assets.
  • [service] is representing a smart city service/application domain for example parking, garbage, environmental etc.
  • [provider] is the logic separator for which service the asset belongs to. For example, in a city, the bus company and waste management company can use common names for different assets, as they use to work in separate silos. In order to avoid that, the [provider] name allows us to avoid the duplication of [entityNames] within the OC Facility for a particular site.
  • [group]: This is optional. The group part can be used for grouping assets under the same service and provider. It is responsibility of OS sites to maintain proper group keys.
  • [entityName]: The Entity/Device identifier which should be unique at the corresponding OC Site, service and provider. The same applies at the scope of an experiment.
type: string

This attribute specifies the type of the asset, e.g., urn:oc:entityType:weatherstation

TimeInstant: object

This attribute encodes the time that an update to the asset has been performed. It must be added by the asset provider. The type is urn:oc:attributeType:ISO8601, while the format for the value is specified by the ISO8601, where the following format is used (the Z at the end means UTC):

YYYY-MM-DDTTHH:mm:ss:SSSZ

Since Dec 1st 2016, the OC Platform just accept assets which provide a valid TimeInstant-attribute. For the sake of a good platform function all other time formats will be rejected.

{
"TimeInstant": {
"type": "urn:oc:attributeType:ISO8601",
"value": "2016-10-04T13:45:00.000Z"
}
,
"id": "urn:oc:entity:london:environmental:hydePark:weatherstation123",
"type": "urn:oc:entityType:weatherstation"
}

AssetUpdate: object

This JSON object represents an asset, if it is updated. The minimal required attrbute is TimeInstant. To update an asset, it is not allowed to use the attributes id and type.

TimeInstant: object

This attribute encodes the time that an update to the asset has been performed. It must be added by the asset provider. The type is urn:oc:attributeType:ISO8601, while the format for the value is specified by the ISO8601, where the following format is used (the Z at the end means UTC):

YYYY-MM-DDTTHH:mm:ss:SSSZ

Since Dec 1st 2016, the OC Platform just accept assets which provide a valid TimeInstant-attribute. For the sake of a good platform function all other time formats will be rejected.

{
"TimeInstant": {
"type": "urn:oc:attributeType:ISO8601",
"value": "2016-10-04T13:45:00.000Z"
}
}

Error: object

These JSON objects are returned when the server encounters an error on processing a request, and needs to explain further error details to the requesting client.

Possible errors:

  • Client errors:
    • You are not a client.
    • ClientID wrong.
    • ClientID wrong. You`re not an OC site.
  • HTTP Header errors
    • HTTP header Content-Type application/xm not acceptable. Please provide application/json.
    • HTTP header Fiware-Service test not acceptable.
  • HTTP Body errors
    • No HTTP body provided.
    • HTTP body is not valid JSON.
  • Asset errors:
    • Asset.id prefix wrong.
    • No Asset ID provided.
    • asset.type prefix must be urn:oc:entityType:
    • Asset attribute TimeInstant in payload not found.
    • Asset attribute TimeInstant.value not provided.
    • Asset attribute TimeInstant.value is not in the required format YYYY-MM-DDTHH:mm:ss.SSSZ
  • Generic errors:
    • The site reached the quota!
  • ...
error: string

The type of th error, e.g., InternalServerError

description: string

A detailed explanation on why the request failed.

{
"description": "No HTTP body provided.",
"error": "InternalServerError"
}