vf-OS Platform

Platform

The vf-OS Platform component provides two fundamental services:

• Portal Services, which realises the holistic encapsulation of the web-based user interfaces of all relevant vf-OS components and vApps into a single coherent user interface
• Execution Services, which provide centralised management of a distributed environment in which all vf-OS components and vApps (and potentially other Assets) are running

Portal Services

The platform's Portal Services provide an infrastructure to render the components' user interfaces and vApps inside a single portal window. It basically provides a reverse proxy setup which makes connections to HTTP servers provided by the individual components and vApps.

Each component and vApp with a user interface is required to provide a HTTP server for this interface supporting at least two different modes: icon mode (for showing an overview of installed components and vApps), and user interface mode. For the user interface mode, each component or vApp may support a selection of three different renderings (but, as said, at least one of these): as a widget (small), as an app (larger, but in a window) and as a full-screen application. Inside the Platform Portal, the end user may provide personal preferences which rendering to use.

The Portal Services will put some restrictions onto the behaviour of the component and vApp user interfaces. Some guidelines for this will be specified here at a later stage.

Execution services

These services contain the following API endpoints

List assets

Via this route, a list of installed assets can be retrieved.

GET /platform/executionservices/assets HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "Id":"8dfafdbc3a40",
    "Name":"vfFailureManager",
    "Version":"1.23",
    "Type":"vApp",
    "Status":"running",
    "Host id":"1lr9wayhc1yxmoifn91d862tv"
  },
  {
    "Id":"9cd87474be90",
    "Name":"ProcessBuilder",
    "Version":"2.12",
    "Type":"component",
    "Status":"running",
    "Host id":"cloud"
  },
  {
    "Id":"3176a2479c92",
    "Name":"vfDocumentPortal",
    "Version":"1.0",
    "Type":"vApp",
    "Status":"idle",
    "Host id":"1lr9wayhc1yxmoifn91d862tv"
  }
]

Request

Request URL: GET /platform/executionservices/assets

Response

Returns a list of installed assets. If successful, this operation returns 200 OK, otherwise an error is returned.

Common status codes returned

Code	Description
200	OK
403	forbidden
500	server error

Install asset

Install an asset with specific parameters. The request installs the asset at the specified host and returns an ID for it. The installed asset has status "idle" (not started) by default.

POST /platform/executionservices/assets HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "Name":"vfDocumentPortal",
  "Version":"1.0",
  "Host id":"cloud"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "id":"e90e34656806"
}

Request

Request URL: POST /platform/executionservices/assets

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
Asset Object	yes	Body entity	JSON object	The asset object consists of the following attributes Name: Name of the asset to install Version: Version of the asset to install Host id: ID of the host on which the asset will be installed, or "cloud"

Response

After succesful installation, the response will be 201 Created and the id of the newly installed asset will be returned.

Common status codes returned

Code	Description
201	created (asset installed successfully)
400	bad parameter
403	forbidden
404	no such asset
406	host unreacheable
409	conflict (asset already installed on host)
500	server error

Start asset

Starts an installed asset.

POST /platform/executionservices/assets/4a9bf2f80763?action=start HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: POST /platform/executionservices/assets/<id>?action=start

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
id	Yes	Resource	string	The identifier of an installed asset

Response

If successful, this operation returns 200 OK, otherwise an error message is sent out.

Common status codes returned

Code	Description
200	OK
304	asset already started
403	forbidden
404	no such asset
500	server error

Stop asset

Stops an installed asset.

POST /platform/executionservices/assets/4a9bf2f80763?action=stop HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: POST /platform/executionservices/assets/<id>?action=stop

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
id	Yes	Resource	string	The identifier of an installed asset

Response

If successful, this operation returns 200 OK, otherwise an error message is sent out.

Common status codes returned

Code	Description
200	OK
304	asset already stopped
403	forbidden
404	no such asset
500	server error

Delete asset

Deletes an installed asset from a host. The asset must already have status "idle".

DELETE /platform/executionservices/assets/4a9bf2f80763 HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /platform/executionservices/assets/<id>

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
id	Yes	Resource	string	The identifier of an installed asset

Response

If successful, this operation returns 200 OK, otherwise an error message is returned.

Common status codes returned

Code	Description
200	OK
403	forbidden
404	no such asset
409	conflict (asset is running)
500	server error

Register host

Registers a host at the platform. The core vf-OS (according to D2.1 Page 19: Publish/subscribe mechanism, System dashboard and Platform container core functionality which manages the overall vf-OS components) must have been installed on the host. The platform will automatically contact the host and connect it to the Platform Execution Services infrastructure.

POST /platform/executionservices/hosts HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "IP Address":"132.101.33.19",
  "Port":"2375"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":"1lr9wayhc1yxmoifn91d862tv"
}

Request

Request URL: POST /platform/executionservices/hosts

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
Host information	Yes	Body entity	JSON Object	The host informatoin consists of the following attributes IP Address: The IP address of the host Port: The port at which the host can be contacted by the platform

Response

If the host can be contacted and the incorporation into the platform is accepted by both parties, the response will be 200 OK. The Host id for this newly registered host will be returned.

Common status codes returned

Code	Description
200	OK
400	bad parameter
401	unauthorized (host does not allow request)
403	forbidden (server does not allow request)
404	not found (host cannot be reached)
500	server error

Unregister host

Unregisters a host at the platform. The host must not contain any installed assets with status "running".

DELETE /platform/executionservices/hosts/1lr9wayhc1yxmoifn91d862tv HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /platform/executionservices/hosts/<host id>

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
host id	Yes	Resource	string	The identifier of a specific host

Response

The response will be 200 OK if no error occurs.

Common status codes returned

Code	Description
200	OK
403	forbidden
405	method not allowed (host still has running assets)
404	no such host
500	server error

List hosts

Provides a list of registered hosts.

GET /platform/executionservices/hosts HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "Host id":"1lr9wayhc1yxmoifn91d862tv",
    "Hostname":"mondragon1",
    "IP address":"10.27.8.102",
    "port":"2375",
    "Status":"ready"
  },
  {
    "Host id":"fneuwfn124u8912ndf3ni102u",
    "Hostname":"viasolis23",
    "IP address":"33.64.13.83",
    "port":"2375",
    "Status":"unreachable"
  }
]

Request

Request URL: GET /platform/executionservices/hosts

Response

If no error occurs, the response will be 200 OK and a JSON array will be returned containing an object for each host with limited information about that host.

Common status codes returned

Code	Description
200	OK
403	forbidden
500	server error

Inspect a host

Provides status information about a specific host.

GET /platform/executionservices/hosts/fneuwfn124u8912ndf3ni102u HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Host id":"fneuwfn124u8912ndf3ni102u",
  "Hostname":"mondragon1",
  "IP address":"10.27.8.102",
  "port":"2375",
  "Status":"ready",
  "Version":"1.01",
  "CreatedAt":"2016-06-07T20:31:11.853781916Z",
  "UpdatedAt":"2016-06-07T20:31:11.999868824Z",
  "Architecture":"x86_64",
  "OS":"linux",
  "NanoCPUs":4000000000,
  "MemoryBytes":8272408576,
  "Status":"ready"
}

Request

Request URL: GET /platform/executionservices/hosts/<host id>

Response

In case the host is found and no other error occurs, the response will be a 200 OK together with a JSON object containing information about the host.

Common status codes returned

Code	Description
200	OK
403	forbidden
404	no such host
500	server error

OAK Toolkit

OAK SDK

The SDK will be able to provide required resources and services to the Studio and to other Application-Development components as well as to access design orientated data stored in vf-OS (models, patterns, and behaviours). The idea is to be able to develop vApps with this framework such as the SDK will provide what needs to be included in the vApp.

Due this fact SDK is an aggregation of multiple vf-OS components, the SDK export exact the same methods of each vf-OS component does. The table below contains a list of these components.

Resource	Description
Marketplace	e-Commerce services
Process Designer	Renders the toolbox to the canvas
Engagement Hub	developer suite of tools
Studio	user-friendly interfaces to create vApps

OAK Studio

The vf-OS Application Design Studio is a holistic GUI supporting vApp developers to easily implement applications by integrating and orchestrating services, APIs, and connectors. The design studio provides necessary tools and means to develop and deploy applications on end user devices to application developers. The developer will be supported by step-by-step procedures which cover the entire development process including the registration of new applications (or updates) on the vf-Store.

The OAK Studio will use all resources the OAK SDK provides.

Frontend Environment

The OAK-Frontend Environment offers a Graphical User Interface (GUI) editor to allow vApp developers the implementation of end-user interfaces for their solutions. The editor will be accessible from within the OAK Studio as a plain browser consuming external microservices. These services provide large ranges of visual templates implemented in HTML5 + CSS3. Developers can combine them within the GUI editor to achieve enclosed vApp visualisations at the end. The templates can stand for themselves (eg customised GUI elements) or contain/bind to additional behaviour and JavaScript logic (eg registration forms or error representation). vApp developers thus will have a high degree of flexibility and power as there are barely any restrictions in merging templates. The OAK Frontend Environment will still develop an abstraction layer concept, subordinating the entities into abstraction levels. This strategy will produce additional guidance for the developer and speed up the process of rapid prototyping. The editor also allows the inheritance of external configuration like translations for internationalisation, as well as internal, individual configurations / attributes for each template itself.

This vf-OS module is subdivided in lower-level modules:

• The Client- Module consists out of nothing more than one single HTML file, processing user inputs and forwarding them to the mirco services module, where necessary calculations for representing vApps take place.
• The Server- Module consists out of multiple Mircoservices working together, which listen to user inputs and transform them into clickable prototypes of a vApp.

The OAK-Frontend partically includes the Process Designer to connect logical aspects to GUI-Elements. Itself, it is consumed by the OAK-Studio, which is responsible to offer any external services needed.

Process Enabler - Designer

The Process Designer is responsible for allowing users to model multiple manufacturing workflows so orchestrating the various assets available within a collaborative framework. The tool will be a reactive, extensible, and an online workspace supporting a BPMN-like model and be utilisable by vApps where process design and orchestration is appropriate.

Use the Process Designer

The actual using of the Process Designer; where the User uses the Process Designer from the Studio. The internal functionalities tu use the Designer are then provided inside the returned json body.

GET https://dev.vfos.eu/designer/prmoui001?userToken=usertoken123 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "processModelUrl":"http://dev.vfos.eu/pro001.xml",
  "format":"XML",
  "version":"1.0"
}

Request

Request URL: GET https://dev.vfos.eu/designer/<processDesignerId>?usertToken=<userToken>

Transfer Parameters

Name	Required	Parameter Type	Type	Description
processDesignerId	yes	Resource	String	The unique identifier of the Process Designer UI
userToken	yes	Query	String	The userToken propagated through all requests

Response

If successful, it returns the Process Designer setup encapsulated inside a XML, and of course additionally a HTTP Statuscode.

Common Status Codes Returned

Code	Description
200	Connected to the Proces Model UI
403	Required permissions not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Data Mapping

Connect Data Source

The RESTful interface Connect Data Source allows setting up the connection to a target or source schema implemented by any data source that may need to access the data source in runtime.

POST http://dev.vfos.eu/mapping/datasources/id245458479ald/connections?session=P3L4CtoKn34 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "schemaUrl":"https:\/\/dev.vfos.eu\/schema\/sch001.dtd",
  "format":"DTD",
  "version":"1.0"
}

HTTP/1.1 201 Created

Request

Request URL: POST http://dev.vfos.eu/mapping/datasources/<ID>/connections?session=<userToken>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
ID	Yes	Resource	String	The unique identfier for the schema to be connected to
userToken	Yes	Query	String	The userToken propagated through all requests
object	Yes	Body entity	Json Array	Setup of the data source

Response

Returns an HTTP Status Code

If there is an error during the processing, a message should be returned to specify detailed information. Otherwise, it is generally expected that a HTTP Status Code will be returned.

Common Return Codes

Code	Description
201	Connection to Schema has been established successfully
400	Invalid Setup
403	Insufficient rights
404	Schema not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get Linked Paths

The RESTful interface Get Linked Paths computes the semantic similarity between two given concepts in the vf-OS Data Model and returns the existing paths between them to certain depth.

GET http://dev.vfos.eu/mapping/linkedConcepts/id2345?target=3f8c&maxDepth=10&session=P3L4CtoKn HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  [
    "id2345",
    "e525",
    "bf13",
    "c9d9",
    "3f8c"
  ],
  [
    "id2345",
    "0182",
    "8f16",
    "3f8c"
  ],
  [
    "id2345",
    "c58e",
    "5628",
    "39f0",
    "3f8c"
  ]
]

Request

Request URL: GET http://dev.vfos.eu/mapping/linkedConcepts/<conceptId1>?target=<conceptId2>&maxDepth=<maxDepth>&session=<userToken>

Resource Parameters

Name	Required	Parameter Type	Object Type	Description
conceptId1	Yes	Resource	String	ID of source concept
conceptId2	Yes	Query	String	ID of target concept
maxDepth	Yes	Query	Integer	Max number of levels to look for linked concepts
userToken	Yes	Query	String	The userToken propagated through all requests

Response

Returns an HTTP Status Code together with a list of paths

If there is an error during the processing, a message should be returned to specify detailed information. Otherwise, it is generally expected that a list of paths that connect two concepts, expressed by their concept IDs.

Common Return Codes

Code	Description
200	Link found
204	No links found between concepts
403	Insufficient rights
404	Some of the concepts were not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get Linked Concepts

The RESTful interface "Get Linked Concepts" retrieves all concepts that are linked to a given concept up to a certain depth and which are compliant with the parameters specified in the call.

GET http://dev.vfos.eu/mapping/linkedConcepts/id2345?type=method&param=descriptionSimilarity&depth=10&session=P3L4CtoKn HTTP/1.1

HTTP/1.1 200  OK
Content-Type: application/json; charset=utf-8

[
  [
    "city",
    "ciudad",
    "ville",
    "village"
  ],
  [
    "city",
    "town",
    "village"
  ],
  [
    "city",
    "stadt",
    "dorf",
    "village"
  ]
]

Request

Request URL: GET http://dev.vfos.eu/mapping/linkedConcepts/<conceptID>?type=<typeOfLink>&maxDepth=<maxDepth>&session=<userToken>

Resource Parameters

Name	Required	Parameter Type	Object Type	Description
conceptID	Yes	Resource	String	Name of the concept
typeOfLink	No	Query	Enumerate	Type of algorithm to be executed. The following values are applicable to this parameter: Simple: No parameters are expected for this type Method: Name of the method to get the related concepts, eg link, name similarity or description similarity Filter: List of conditions to get the related concepts, eg Lan: EN; Domain: Geography
maxDepth	No	Query	Integer	Max number of levels to look for linked concepts
userToken	Yes	Query	String	The userToken propagated through all requests

Response

Returns an HTTP Status Code together with a JSON-LD list of concepts

If there is an error during the processing, a message should be returned to specify detailed information. Otherwise, it is generally expected that a list of concepts is returned in the form of a JSON-LD.

Common Return Codes

Code	Description
200	Linked Concepts found
204	No Linked Concepts found
403	Insufficient rights
404	Concept not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Search Linked Concepts

The RESTful interface Search Linked Concepts retrieves all concepts that are matching to a given keyword up to a certain depth. If no keyword is provided, all linked concepts will be returned.

GET http://dev.vfos.eu/mapping/linkedConcepts?keyword=city&maxDepth=10&session=P3L4CtoKn HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  [
    "ciudad",
    "ville",
    "village",
    "town",
    "stadt",
    "dorf"
  ]
]

Request

Request URL: GET http://dev.vfos.eu/mapping/linkedConcepts?keyword=<searchKeyword>&maxDepth=maxDepth&session=userToken

Resource Parameters

Name	Required	Parameter Type	Object Type	Description
searchKeyword	No	Query	String	Name of the concept to be searched
maxDepth	No	Query	Integer	Max number of levels to look for linked concepts
userToken	Yes	Query	String	The userToken propagated through all requests

Response

Returns an HTTP Status Code together with a JSON-LD list of concepts

If there is an error during the processing, a message should be returned to specify detailed information. Otherwise, it is generally expected that a list of concepts is returned in the form of a JSON-LD.

Common Return Codes

Code	Description
200	Concepts found
403	Insufficient rights
404	Concept not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Engagement

Developer Engagement

The purpose of the vf-OS Developer Engagement Hub is to define and develop a suite of tools that fit together and consist of a platform to support developer collaboration between developers, customers, and communities.

Note that it does not itself facilitate vf-OS programming which is through the vf-OS SDK, Studio, etc. but will facilitate programming

Upload Resource

Allows the upload of documentation from all parts of the vf-OS framework. This can include documents, but also elements in other media formats.

POST /v1/deh/resource HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "resourceUrl":"<path for resource>",
  "type":"mp4"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "resourceUrl":"<path for resource in deh>"
  }
}

Request

Request URL: POST /v1/deh/resource

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
resourceUrl	Yes	Body entity	String	Url of a resource you want to upload
type	Yes	Body entity	String	Type of resource to upload

Response

Returns a list of uploaded resources. If successful, this operation returns 200 OK, otherwise an error is returned.

Common Return Codes

Code	Meaning
200	OK
400	Bad request
403	Forbidden
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get Code

Retrieves code from codehosting component export code in files. The Developer Engagement Hub exports an interface to obtain code in order to allow the SDK to build and compile.

GET /v1/deh/codehosting HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "codeId":"10"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "codeFileUrl":"/path/for/code"
  }
}

Request

Request URL: GET /v1/deh/codehosting/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
codeId	Yes	Body entity	String	Code sample id

Response

If success, get code file from codehosting.

Common Return Codes

Code	Meaning
200	OK
403	Required permissions not found
403	Forbidden
404	Not Found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Submit Ticket

Allow to create modify and comment a issue in issue tracker.

POST /v1/deh/issuetracker HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "issueBody":"Issues in component n10",
  "issueTitle":"Issue when dashboard are been loading",
  "type":"issue"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "issuePath":"/path/for/issue"
  }
}

Request

Request URL: POST /v1/deh/issuetracker

Transfer Parameters

Name	Required	Type	Description
issueBody	Yes	String	Description of the issue
issueTitle	Yes	String	Title of the issue
type	Yes	String	Specifies the type of issue, suggestion

Response

If success, have added ticket in issue tracker otherwise an error is returned.

Common Return Codes

Code	Meaning
200	OK
403	Required permissions not found
403	Forbidden
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Upload Document

Add a document in documentation module, this document can be related to a specific version of code or with release.

POST /v1/deh/wiki HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "version":"v1.0",
  "documentUrl":"/path/document"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "message":"document was successfully added."
  }
}

Request

Request URL: POST /v1/deh/wiki

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
version	No	Body entity	String	link the document to a version
documentUrl	Yes	No	Body entity	Url of document

Response

If success, submit document to documentation system otherwise will return error.

Common Return Codes

Code	Meaning
200	OK
403	Required permissions not found
403	Forbidden
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Developer Engagement and Training

All vf-OS components provide an environment for developers in terms of the vf-P, vf-Store, vf-OAK as well as the vf-Studio and the Frontend Environment. Whilst this provides a ‘typical’ facility and environment for developers, it is helpful to reach a critical mass to reach multiple developers by further encouraging and educating them. This not only applies for internal developers but also external developers who can later become the customers of “vfOS Limited” and can help to prove the system.

uploadResource()

Request

Request URL: POST https://dev.vfos.eu/marketplace/api/models?processmodel=processModel

Resource Parameters

Name	Required	Type	Description
processModel	Yes	ProcessModel	Process model
userToken	Yes	String	User Token propagated through all requests

Response

Render toolbox elements to the canvas

Common Return Codes

Code	Meaning
200	OK
401	Required permissions not found
402	Marketplace not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

getCode()

Returns the BPMN elements from the BPMN library

Request

Request URL: GET https://dev.vfos.eu/designer/api/bpmnelements/{ID}

Resource Parameters

Name	Required	Type	Description
userToken	Yes	String	User Token propagated through all requests
filterString	No	String	String used to filter BPMN Elements
sortString	No	String	String used to sort BPMN Elements

Response

If successful, it returns the BPMN elements and returns with HTTP Statuscode

Common Return Codes

Code	Meaning
200	OK
401	Required permissions not found
402	Marketplace not found
403	BPMN Element not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

submitTicket()

Inserts a BPMN Model into BPMN Marketplace

Request

Resource Parameters

Response

If successful, posts the Model to the Marketplace and returns a HTTP Statuscode

Common Return Codes

Code	Meaning
200	OK
401	Required permissions not found
402	Marketplace not found
403	BPMN Element not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

uploadDocument()

Updates a BPMN Model in the BPMN Marketplace

Request

Resource Parameters

Response

Common Return Codes

Code	Meaning
200	OK
401	Required permissions not found
402	Marketplace not found
403	BPMN Element not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

getMetric()

Request

Resource Parameters

Response

Common Return Codes

Code	Meaning
200	OK
401	Required permissions not found
402	Marketplace not found
403	BPMN Element not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

hubFunctionalities()

Connects to the Toolbox and returns elements

Request

Request URL: GET https://dev.vfos.eu/designer/api/bpmnelements/{ID}

Resource Parameters

Name	Required	Type	Description
userToken	Yes	String	User Token propagated through all requests
filterString	No	String	String used to filter BPMN Elements
sortString	No	String	String used to sort BPMN Elements

Response

If successful, it returns the Toolbox elements and returns with HTTP Statuscode

Common Return Codes

Code	Meaning
200	OK
401	Required permissions not found
402	Toolbox not found
404	Process Instance not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Middleware

The vf-Middleware provides an infrastructure, which enables components and vf-Assets to comunicate directly or even-driven . Two different compnents are foreseen to handle the communication in vf-OS. First the Messaging, which enables a direct communication, and second the event-driven approach via the Publish/Subscribe component. And finally, the Process Enabler for Execution handles the execution of vf-OS Assets and components.

Messaging

The Messaging component provides functionalities to enable message flow between vf-OS components. The messages consist of requests, reports, or events that are dispatched by one component and consumer by other component(s). The controlling actions involve creation of communication channels, routing, queue management, etc. The URL is presented in the following format:

http://dev.vfos.eu/messaging/

Create a Connection

Create a connection with the name connectionName. A connection is in the stopped state when it is created unless the start action is specified in the PUT request to create the connection.

POST /connections HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "connectionName":"connection1",
  "action":"active",
  "clientID":"clientId1"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "connection":{
        "metadata":{
          "channelProperties":{
            "items":[
              "deliverycount",
              "groupID",
              "groupSeq"
            ]
          }
        },
        "canonicalLink":"relative path to newly created connection"
      }
    }
  ]
}

Request

The request contains all necessary information to create a connection. It contains multiple fields, but only connectionName is required.

Request URL: POST /connections

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
connectionName	Yes	Body	string	Name of the connection
action	No	Body	string	Desired status of the connection
clientID	No	Body	string	Identification of the client

Response

The response contains the status of creating the connection. If it returns an error, it will also return the error description.

Error Messages

• clientIdFailure: The value provided for the client ID was rejected by the JMS provider. The value of the client ID may be in use by another application, including message push listeners.
• maxLocalConnectionsReached: The service instance has exceeded the number of connections it can create on a single virtual machine in the cloud. This usually means that the service instance has reached, or even gone beyond, the maximum number of allowed connections.
• connectionAlreadyExists: A connection with the specified name already exists.
• maxConnectionCountUnavailable: An internal error has occurred in determining the number of connections that a service instance is allowed.
• operationFailed: A low-level exception occurred in attempting to create the connection.

Update a Connection

Update connection properties

PUT /connections/<connectionName> HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "action":"inactive"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success"
}

Request

The request contains multiple fields, only connectionName is required.

Request URL: PUT /connections/<connectionName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
connectionName	Yes	Body	string	Name of the connection
action	No	Body	string	Status of the connection
clientID	No	Body	string	Identification of the client

Response

The response contains the status of updating the connection as well its response code. If it returns an error, it will also return the error description.

Error Messages

• clientIdFailure: The value provided for the client ID was rejected by the JMS provider. The value of the client ID may be in use by another application, including message push listeners.
• maxLocalConnectionsReached: The service instance has exceeded the number of connections it can create on a single virtual machine in the cloud. This usually means that the service instance has reached, or even gone beyond, the maximum number of allowed connections.
• maxConnectionCountUnavailable: An internal error has occurred in determining the number of connections that a service instance is allowed.

Delete a Connection

Delete a connection

DELETE /connections/<connectionName> HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success"
}

Request

Only connectionName is required.

Request URL: DELETE /connections/<connectionName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
connectionName	Yes	Resource	string	Name of the connection

Response

The response contains the status of deleting the connection as well its response code. If it returns an error, it will also return the error description.

Create a Consumer

Create a consumer with the given name.

POST /consumers HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "consumerName":"consumer1"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "connection":{
        "metadata":{
          "channelProperties":{
            "items":[
              "deliverycount",
              "groupID",
              "groupSeq"
            ]
          }
        },
        "canonicalLink":"relative path to newly created consumer"
      }
    }
  ]
}

Request

The request contains the consumerName, which is a mandatory field.

Request URL: POST /consumers

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
consumerName	Yes	Body	string	Name of the consumer

Response

The response contains the status of creating the consumer as well its response code. If it returns an error, it will also return the error description.

Possible Return Codes

• missingParameter: The request had no required parameter specified.
• badParameter: The value of the timeout parameter did not parse as a long integer value, or the value of the timeout parameter was 0 or a negative number.
• timeoutTooLarge: The value of the timeout parameter was larger than the maximum allowed value.
• consumerAlreadyExists : The requested consumer name already exists.
• operationFailed: A low-level exception was thrown while receiving, or an exception was thrown while attempting to extract information from the received message.

Delete a Consumer

Delete a Consumer

DELETE /consumers/<consumerName> HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success"
}

Request

Only consumerName is required.

Request URL: DELETE /consumers/<consumerName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
consumerName	Yes	Resource	string	Name of the consumer

Response

The response contains the status of deleting the consumer as well its response code. If it returns an error, it will also return the error description.

Possible Return Codes

• timeoutTooLarge: The value of the timeout parameter was larger than the maximum allowed value.
• consumerNotFound: The requested consumer does not exist.
• operationFailed: A low-level exception was thrown while receiving, or an exception was thrown while attempting to extract information from the received message.

Get messages from a specific Consumer

Method to receive a message by the consumer. Clients receive messages by using a session to create a consumer. A session can have multiple consumers. Consumers persist until they are closed or the session in which they were created is closed.

If there is a message on the consumer's queue that satisfies the selector (if it was set on the consumer) or if one enters the queue within the number of milliseconds in timeout, it is returned in the HTTP response. Otherwise, a null message is returned. If receiving from a topic, if messages have been published to the topic since the consumer was created, or if messages are published to the topic within the number of milliseconds in timeout, one of those messages will be returned in the HTTP response. Otherwise a null message is returned.

If the consumer is consuming from a durable subscription, and if there is a message currently stored in the durable subscription, or if one enters the durable subscription within the number of milliseconds in timeout, it is returned in the HTTP response. Otherwise, a null message is returned.

GET /consumers/<consumerName>/messages HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "message":"Message successfully received from vf-OS component."
    }
  ]
}

Request

The request contains the consumerName, which is a mandatory field.

Request URL: GET /consumers/<consumerName>/messages

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
consumerName	Yes	Resource	string	Name of the consumer

Response

The response contains the status of creating the consumer as well its response code. The response also has the message content.

Possible Return Codes

• badParameter: The value of the timeout parameter did not parse as a long integer value, or the value of the timeout parameter was 0 or a negative number.
• timeoutTooLarge: The value of the timeout parameter was larger than the maximum allowed value.
• consumerNotFound: The requested consumer does not exist.
• operationFailed: A low-level exception was thrown while receiving, or an exception was thrown while attempting to extract information from the received message.

Create a Producer

Create a producer with the given name.

POST /producers HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "producerName":"producerIdentification",
  "destination":"destinationExample"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "producer":{
        "metadata":{
          "channelProperties":{
            "items":[
              "deliverycount",
              "groupID",
              "groupSeq"
            ]
          }
        },
        "canonicalLink":"relative path to newly created consumer"
      }
    }
  ]
}

Request

The request contains the producerName, which is a mandatory field.

Request URL: POST /producers

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
producerName	Yes	Body	string	Name of the producer

Response

The response contains the status of creating the producer as well its response code. If it returns an error, it will also return the error description.

Possible Return Codes

• forbiddenContentType: The Content-Type header of the HTTP request had forbidden value.
• multipleDestinations: Either the producer has no default destination and no destination was specified by the request, or the producer has a default destination and a destination was specified by the request..
• messageBodyTooLarge: The request's body exceeded the maximum size.
• maxMessagesOnTargetDestinationReached : The service instance already has the maximum number of messages on the specified destination of the message.
• producerAlreadyExists: The requested producer name already exists.
• operationFailed:The server was unable to obtain the input stream containing the message body, or a low-level exception was thrown while trying to send the message.

Update a Producer

Update producer properties

PUT /producers/producerName HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "destination":"newDestination"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success"
}

Request

The request contains multiple fields, but only producerName is required.

Request URL: PUT /producers/<producerName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
producerName	Yes	Body	string	Name of the producer
metadataToBeUpdated	No	Body	Object	Properties of the producer to be updated

Response

The response contains the status of updating the producer as well its response code. If it returns an error, it will also return the error description.

Possible Return Codes

• forbiddenContentType: The Content-Type header of the HTTP request had forbidden value.
• producerNotFound: The requested producer does not exist.
• operationFailed: The server was unable to obtain the input stream containing the message body, or a low-level exception was thrown while trying to send the message.

Delete a Producer

Delete a Producer

DELETE /producers/producerName HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success"
}

Request

Only producerName is required.

Request URL: DELETE /producers/<producerName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
producerName	Yes	Resource	string	Name of the producer

Response

The response contains the status of deleting the producer as well its response code. If it returns an error, it will also return the error description.

Possible Return Codes

• timeoutTooLarge: The value of the timeout parameter was larger than the maximum allowed value.
• producerNotFound: The requested producer does not exist.
• operationFailed: A low-level exception was thrown while receiving, or an exception was thrown while attempting to extract information from the received message.

Send Message to a specific producer

Send the message specified by the HTTP headers and request body to the destination specified. Clients send messages by using a session to create a producer. A session can have multiple producers. Producers persist until they are closed or the session in which they were created is closed. A producer defines the default characteristics of messages sent through the producer. A producer can specify the destination to which all messages are sent, how sent messages should be stored in the service, and how long sent messages are stored in the service before they expire.

POST /producers/producerName/messages HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "deliveryMode":{
    "persistent":"non_persistent"
  },
  "destination":{
    "component":"exampleComponent"
  },
  "replyTo":{
    "component":"vfOsComponent"
  },
  "message":{
    "message":"This message will be delivered."
  }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "producer":{
        "metadata":{
          "channelProperties":{
            "items":[
              "deliverycount",
              "groupID",
              "groupSeq"
            ]
          }
        },
        "canonicalLink":"relative path to newly created consumer"
      }
    }
  ]
}

Request

The request contains the producerName, which is a mandatory field.

Request URL: POST /producers/<producerName>/messages

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deliveryMode	NO	Body	Object	Whether messages are required to be stored in persistent storage. If present, the value must be persistent or non_persistent; default is persistent. If the value is persistent, the message must be stored in persistent storage; otherwise, it may or may not be stored in persistent storage. Messages in persistent storage can persist through outages or failover of the service.
destination	YES	Body	Object	Required if the producer was not created with a destination; otherwise, it is forbidden. The value is the destination to which the message will be sent. If present they can be linked with the available queues or topics
groupId	NO	Body	Object	The value of the groupId property on the message being sent. This parameter is optional, but should be set if, and only if, groupSeq is set.
groupSeq	NO	Body	Object	The value of the groupSeq property on the message being sent. This is the sequence number of the message within the message group specified by the groupId parameter. This parameter is optional, but should be set if, and only if, groupId is set.
replyTo	NO	Body	Object	The value is a destination to which replies should be sent. This is useful for message exchanges which can have asynchronous responses.

Response

The response contains the status of creating the producer as well its response code. If it returns an error, it will also return the error description.

Possible Return Codes

• forbiddenContentType: The Content-Type header of the HTTP request had forbidden value.
• multipleDestinations: Either the producer has no default destination and no destination was specified by the request, or the producer has a default destination and a destination was specified by the request..
• messageBodyTooLarge: The request's body exceeded the maximum size.
• maxMessagesOnTargetDestinationReached : The service instance already has the maximum number of messages on the specified destination of the message.
• producerNotFound: The requested producer does not exist.
• operationFailed: The server was unable to obtain the input stream containing the message body, or a low-level exception was thrown while trying to send the message.

Process Enabler - Executions

The Process Execution is the part of the Process Enabler component that deals with the runtime aspect; executing a firmly defined workflow.

Execute Process

This interface will receive the deployed process from the vApps/vf-OS Assets to execute it

POST http://dev.vfos-eu/processenabler-execution/process/1234/instances HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "instance":"http://dev.vfos-eu/processenabler-execution/processes/1234/instances/instance001.xml",
  "format":"XML",
  "version":"1.0"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "type":"termination",
  "response":"execution"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "type":"termination",
  "response":"failure"
}

Request

Request URL: POST http://dev.vfos-eu/processenabler-execution/process/<processModelId>/instances/

Transfer Parameters

Name	Required	Parameter Type	Type	Description
processId	Yes	Resource	String	A unique identifier for a specific process model
model XML	Yes	Body entity	JSON Object	An object with the setup of an instance, which contains the following attributes Type: Defines if the execution was successfull (type=execution) or not (type=failure) response: Array of key value pairs representing the return values reason: Message containing the reason for the failure

Response

If successful, the response will return with an HTTP Statuscode 201.

Common Status Codes Returned

Code	Description
201	An instance of a process has been started
404	The process cannot be found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Data Management

The data management in vf-OS is mainly managed by the components Data Storage, Data Transformation and Data Analytics.

• Data Storage: All vf-OS relevant data can be stored and retrieved centrally from this component and is provided to all vf-OS components and vf-Assets. The Data Storage component is composed of three repositories depending on the data to be stored: Relational DB, a Document-oriented storage, and a Time-Series DB.
• Data Transformation: If some data isn´t in the expected format by the vApp, then they can be transformed into the expected format by designing first the transformation maps (using the Data Mapping component) and then executing these maps within this component.
• Data Analytics: Finally, analytics functions can be executed by this component on top of the data shared within the vf-OS environment.

Data Storage - Basics

General URL

Requests are formatted with the following common variables.

Name	Example	Description
hostname	api.vfos.com	Specifies the server host
port	7777	Specifies the server port
version	3.0	Cloud Storage API version
resource_uri	databases/database1	The uri of the resource

The URL is presented in the following format:

https://<hostname>:<port>/<version>/<resource_uri>

The left part of the URL, up to the resource_uri, is common to all the API endpoints, so it will not be repeated in every interface in this documentation.This should be prefixed to every endpoint:

Database Credentials

All the functions in this API must use database credentials (username and password). This will be set in header of the request, as HTTP Basic Authentication will be used.

If this information is not provided, or if the credentials are not valid, a 401 Unauthorized status code will be returned. On the other hand, if the user has not enough privileges to perform the requested action a 403 Forbidden status code will be returned.

Error message

Every API call may succeed or fail.

In case of success the response body will be different in every case, so it will be specified in each API function description. In the case of failure, the response body will include an entry called error. Its value will be a string explaining the error. In order to avoid repetition, this information will not be included in each API function description.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error":"The database XXX does not exist"
}

Content-Type

The content type, for requests as well as for responses will be JSON.

Request and response examples

This guide includes request and response examples. For the shake of clarity examples do not include not relevant information, as the following.

POST https://api.vfos.com:7777/3.0/doc/databases HTTP/1.1
Authorization: Basic xXVXdHXzXXX6XzRXJXVXSXVXOXRXXTX1XktXJmXeX1XXeXx=Host: clip.xxxxxx.eu:8443
Accept: */*
Content-Type: application/json; charset=utf-8
Content-Length: 25

HTTP/1.1 200 OK
Date: Fri, 06 May 2016 12:21:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 100
Connection: keep-alive

Data Storage - Relational Storage

This section describes functionalities regarding relational database storage.

Create Relational Database

Creates a new relational database

POST https://api.vfos.com:7777/3.0/rel/databases HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "database_name":"myRelationalDatabase"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /rel/databases

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Body	String	ID (name) of the database

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Database Created
409	Database already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Drop Relational Database

Drops an existing relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database to be deleted

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Relational Database Tables

Gets the list of tables (catalog) of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "tables":[
    "myTable",
    "myTable2"
  ]
}

Request

Request URL: GET /rel/databases/<database_name>/tables

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the tables of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Relational Database Views

Gets the list of views of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/views HTTP/1.1

HTTP/1.1 200 Success
Content-Type: application/json; charset=utf-8

{
  "views":[
    "myView1",
    "myView"
  ]
}

Request

Request URL: GET /rel/databases/<database_name>/views

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the views of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
404	Database not found
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Relational Table

Creates a table in a given relational database.

POST https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "table_name":"myTable",
  "table_definition_schema":[
    {
      "name":"Name",
      "type":"string",
      "description":"User's name"
    },
    {
      "name":"Email",
      "type":"string",
      "description":"User's email"
    },
    {
      "name":"Age",
      "type":"integer",
      "description":"User's age"
    }
  ]
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /rel/databases/<database_name>/tables

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
table_name	Yes	Body	String	ID (name) of the table
table_definition_schema	Yes	Body	JSON Object	Schema of the table. The exact schema definition format will be specified at a later time. Currently the following attributes are defined name: The name of a column type: the object type of the attribute description: The description of this column

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Table created
400	Bad request. There are errors in the specification of the table
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
409	Table already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Relational Table

Drops an existing table of a given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/tables/<table_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
table_name	Yes	Resource	String	Identifier for the targeted table

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Alter Relational Table

Alters a table definition in a given relational database.

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "table_alteration_schema":[
    {
      "name":"Name",
      "type":"string",
      "description":"System user's name"
    },
    {
      "name":"Email",
      "type":"string",
      "description":"User's email"
    }
  ]
}

HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<database_name>/tables/<table_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
table_alteration_schema	Yes	Body	String	Alteration schema for the table. The exact alteration schema definition format will be specified at a later time.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Ok. Table altered.
400	Bad request. There are errors in the specification of the alteration of the table
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Create Relational View

Creates a view in a given relational database.

POST https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/views HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "view_name":"myView",
  "view_definition_schema":"Name as USERNAME, email as CONTACT from myTable"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /rel/databases/<database_name>/views

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
view_name	Yes	Body	String	ID (name) of the view
view_definition_schema	Yes	Body	String	Schema of the view. The exact schema definition format will be specified at a later time.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	View created
400	Bad request. There are errors in the specification of the view
404	Database not found
409	View already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Drop Relational View

Drops an existing view of a given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/views/myView HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/views/<view_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
view_name	Yes	Resource	String	Identifier for the targeted view

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or view) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Alter Relational View

Alters a view definition in a given relational database. It is a full redefinition of the view, so it's similar to drop and create it again.

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/views/myView HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "view_definition_schema":"Name as USERNAME, email as CONTACT from myTable"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<database_name>/views/<view_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
view_name	Yes	Resource	String	Identifier for the targeted view
view_definition_schema	Yes	Body	String	Schema of the view. The exact schema definition format will be specified at a later time.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Ok. View altered.
400	Bad request. There are errors in the specification of the alteration of the view
404	Resource (database or view) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Create Relational Index

Creates an index in a table of a given relational database.

POST https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/indexes HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "index_name":"myIndex",
  "index_definition_schema":[
    "Name",
    "Email"
  ]
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /rel/databases/<database_name>/tables/<table_name>/indexes

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
index_name	Yes	Body	ID String	ID (name) of the index
index_definition_schema	Yes	Body	String	Schema of the index. The exact schema definition format will be specified at a later time.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Index created
400	Bad request. There are errors in the specification of the index
404	Resource (database or table) not found
409	Index already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Drop Relational Index

Drops an existing index of a table of given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/indexes/myIndex HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/tables/<table_name>/indexes/<index_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
index_name	Yes	Resource	String	Identifier for the targeted index

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, table or index) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Describe Relational Table

Gets a description of a table of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tabl
es/myTable HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "definition":[
    {
      "name":"Name",
      "type":"string",
      "description":"User�s name"
    },
    {
      "name":"Email",
      "type":"string",
      "format":"email",
      "description":"User�s email"
    },
    {
      "name":"Age",
      "type":"integer",
      "description":"User�s age"
    }
  ]
}

Request

Request URL: GET /rel/databases/<database_name>/tables/<table_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table

Response

Returns a status code. In case of success it also returns a table definition and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Describe Relational View

Gets a description of a view of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/views/myView HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "definition":[
    {
      "name":"USERNAME",
      "type":"string"
    },
    {
      "name":"CONTACT",
      "type":"string"
    }
  ]
}

Request

Request URL: GET /rel/databases/<database_name>/views/<view_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
view_name	Yes	Resource	String	Identifier for the targeted view

Response

Returns a status code. In case of success it also returns a view definition and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
404	Resource (database or view) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Insert Relational Rows

Inserts rows in a table in a given relational database.

POST https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "row_values":[
    {
      "Name":"John",
      "Email":"[email protected]",
      "Age":32
    },
    {
      "Name":"Mary",
      "Email":"[email protected]",
      "Age":41
    }
  ]
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "rowIDs":[
    "0001",
    "0002"
  ]
}

Request

Request URL: POST /rel/databases/<database_name>/tables/<table_name>/rows

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_values	Yes	Body	JSON Array	List of rows. The format should be a list (rows) of lists (columns) of values, in the format "column_name":"value".

Response

Returns a status code and a list or created rowIDs in case of success, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Rows inserted
400	Bad request. There are errors in the specification of row values
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Delete Relational row

Deletes a row in a table of given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows/1234 HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/tables/<table_name>/rows/<row_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_id	Yes	Resource	String	Identifier for the targeted row

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Delete Relational rows

Deletes a set of rows in a table of given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "filter":"Name = 'John' and Age < 18"
}

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/tables/<table_name>/rows

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
filter	No	Body	String	Filter of the rows. It will be an string specifying the WHERE clause. If not specified, all the rows will be deleted.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Merge Relational row

Updates an existing row updating the selected properties and keeping the values of the not selected ones.

PATCH https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows/1234 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "row_values":{
    "Email":"[email protected]",
    "Age":33
  }
}

HTTP/1.1 200 OK

Request

Request URL: PATCH /rel/databases/<database_name>/tables/<table_name>/rows/<row_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_id	Yes	Resource	String	Identifier for the targeted row
row_values	Yes	Body	JSON Array	List of values. The format should be a list of values, in the format "column_name":"value".

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, table or row) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Merge Relational rows

Updates a set of rows updating the selected properties and keeping the values of the not selected ones.

PATCH https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows HTTP/1.1
Content-Type: application/json; charset=utf-8
{
  "row_values":{
    "Email":"[email protected]",
    "Age":33
  },
  "filter":"Name = 'John' and Age < 18"
}

HTTP/1.1 200 OK

Request

Request URL: PATCH /rel/databases/<database_name>/tables/<table_name>/rows

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_values	Yes	Body	JSON Array	List of values. The format should be a list of values, in the format "column_name":"value".
filter	No	Body	String	Filter of the rows. It will be an string specifying the WHERE clause. If not specified, all the rows will be merged.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Update Relational row

Updates an existing row updating the selected properties and deleting the values of the not selected ones. It is equivalent to a delete+insert.

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows/1234 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "row_values":{
    "Name":"John Jr",
    "Email":"[email protected]",
    "Age":33
  }
}

HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<database_name>/tables/<table_name>/rows/<row_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_id	Yes	Resource	String	Identifier for the targeted row
row_values	Yes	Body	JSON Array	List of values. The format should be a list of values, in the format "column_name":"value".

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, table or row) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Update Relational rows

Updates a set of rows updating the selected properties and deleting the values of the not selected ones.

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "row_values":{
    "Name":"John Jr",
    "Email":"[email protected]",
    "Age":33
  },
  "filter":"Name = 'John' and Age < 18"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<database_name>/tables/<table_name>/rows

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_values	Yes	Body	Array	List of values. The format should be a list of values, in the format "column_name":"value".
filter	No	Body	String	Filter of the rows. It will be an string specifying the WHERE clause. If not specified, all the rows will be merged.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Query Relational row

Queries a table of a relational database with a known row identifier.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows/1234?columns=%5B%22Name%22%2C+%22Age%22%5D HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: GET /rel/databases/<database_name>/tables/<table_name>/rows/<row_id>?columns=<columns>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
row_id	Yes	Resource	String	Identifier for the targeted row
columns	No	Query	JSON Object	Column list. If not specified, all the colums in the table/view will be returned.

Response

Returns a status code. In case of success it also returns the selected row, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, table or row) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Query Relational rows

Queries a table or view of a relational database

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/rows?columns=%5B%22Name%22%2C+%22MAX%28Age%29%22%5D%0D%0A&filter=Name+%3D+%27John%27+and+Age+%3C+18&group_by=Name&skip=3&limit=20 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "documents":[
    {
      "Name":"John",
      "MAX(Age)":11
    }
  ]
}

Request

Request URL (tables): GET /rel/databases/<database_name>/tables/<table_name>/rows?colums=<columns>&filer=<filter>&skip=<skip>&limit=<limit>&group_by=<group_by>&having=<having>&order_by=<order_by> Request URL (views): GET /rel/databases/<database_name>/views/<view_name>/rowscolums=<columns>&filer=<filter>&skip=<skip>&limit=<limit>&group_by=<group_by>&having=<having>&order_by=<order_by>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
table_name	Yes	Resource	String	Identifier for the targeted table
view_name	Yes	Resource	String	Identifier for the targeted view
columns	No	Query	JSON Array	Column list. The columns can be real column names or aggregation expressions (MAX, MIN, AVG...). If not specified, all the colums in the table/view will be returned.
filter	No	Query	String	Filter of the rows. It will be an string specifying the WHERE clause of the select. If not specified, all the rows will be selected.
skip	No	Query	Integer	Specifies the first number of results to be ignored (not returned). Used usually for pagination.
limit	No	Query	Integer	Specifies the maximum number of results to be returned
group_by	No	Query	String	Creates a group for each combination of column expressions. It will be an string specifying the GROUP BY clause of the select.
having	No	Query	String	Specifies a search condition for a group or an aggregate. It will be an string specifying the HAVING clause of the select.
order_by	No	Query	String	Order criteria of the rows. It will be an string specifying the ORDER BY clause of the select.

Response

Returns a status code. In case of success it also returns a list of the selected rows, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or table) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Create Relational Role

Creates a role in a given relational database.

POST https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/roles HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "role_name":"myRole"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /rel/databases/<database_name>/roles

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier of the targeted database
role_name	Yes	Body	String	ID (name) of the role

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Role created
400	Bad request. There are errors in the specification of the role
404	Database not found
409	Role already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Drop Relational Role

Drops an existing role of a given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/roles/myRole HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	Identifier for the targeted database
role_name	Yes	Resource	String	Identifier for the targeted role
password	Yes	Body	String	Password

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Catalog Relational Roles

Gets the list of roles (catalog) of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/roles HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "roles":[
    "role1",
    "role2"
  ]
}

Request

Request URL: GET /rel/databases/<database_name>/roles

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database

Response

Returns a status code. In case of success it also returns a catalog (list) of the roles of the database and in case of error, an error message in the response body.

Common Status Codes

Code	Description
200	Success
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Create Relational User

Creates a user in a given relational database.

POST https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "new_user_name":"anotherUser",
  "new_user_password":"anotherUserPwd"
}

HTTP/1.1 201 User created

Request URL: POST /rel/databases/<database_name>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
new_user_name	Yes	Body	String	ID (name) of the user
new_user_password	Yes	Body	Password of the user

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	User created
400	Bad request. There are errors in the specification of the user
404	Database not found
409	User already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Drop Relational User

Drops an existing user of a given relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users/anotherUser HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
user_name	Yes	Resource	String	ID (name) of the user

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or user) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Catalog Relational Users

Gets the list of users (catalog) of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "users":[
    "user1",
    "user2"
  ]
}

Request

Request URL: GET /rel/databases/<database_name>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database

Response

Returns a status code. In case of success it also returns a catalog (list) of the users of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Add Relational role to user

Grants the privileges of a role to a given user in a relational database.

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users/anotherUser/roles/editor HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<database_name>/users/<user_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
user_name	Yes	Resource	String	ID (name) of the user
role_name	Yes	Resource	String	Identifier for the targeted role

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Delete Relational role to user

Revokes the privileges of a role to a given user in a relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users/anotherUser/roles/editor HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<database_name>/users/<user_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
user_name	Yes	Resource	String	Identifier for the targeted user
role_name	Yes	Resource	String	Identifier for the targeted role

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Grant permissions Relational

Grants permissions to a role or user in a relational database.

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users/anotherUser HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "permissions":"SELECT",
  "scope":"myTable"
}

PUT https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/roles/editor HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "permissions":"INSERT",
  "scope":"myTable"
}

HTTP/1.1 200 OK

Request

Request URL (role): PUT /rel/databases/<database_name>/roles/<role_name> Request URL (user): PUT /rel/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
user_name	Yes	Resource	String	Identifier for the targeted user
role_name	Yes	Resource	String	Identifier for the targeted role
permissions	Yes	Body	JSON String	List of permissions. The exact format will be will be specified at a later time.
scope	Yes	Body	JSON String	Scope the permissions will be applied. The exact format will be will be specified at a later time.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Revoke permissions Relational

Revokes permissions to a role or user in a relational database.

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users/anotherUser HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "permissions":"SELECT",
  "scope":"myTable"
}

DELETE https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/roles/editor HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "permissions":"INSERT",
  "scope":"myTable"
}

HTTP/1.1 200 OK

Request

Request URL (role): DELETE /rel/databases/<database_name>/roles/<role_name> Request URL (user): DELETE /rel/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
user_name	Yes	Resource	String	Identifier for the targeted user
role_name	Yes	Resource	String	Identifier for the targeted role
permissions	Yes	Body	JSON String	List of permissions. The exact format will be will be specified at a later time.
scope	Yes	Body	JSON String	Scope the permissions will be revoked. The exact format will be will be specified at a later time.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Query user permissions Relational

Gets the list of permissions of a user of a given relational database.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/users/anotherUser HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "permissions_and_scope":[
    "GRANT USAGE ON *.* TO `jeffrey`@`localhost`",
    "GRANT SELECT, INSERT, UPDATE ON `db1`.* TO `jeffrey`@`localhost"
  ]
}

Request

Request URL: GET el/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	identifier for the targeted database
user_name	Yes	Resource	String	Identifier for the targeted user

Response

Returns a status code. In case of success it also returns a catalog (list) of the permissions and scope of the database and in case of error, an error message in the response body.

JSON response body parameters

Name	Type	Description
pemissions_and_scope	JSON Object	List of pemissions.

Common status codes returned

Code	Description
200	Success
404	Resource (database or user) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Data Storage - Document Oriented Storage (NoSQL)

This section describes functionalities regarding non-relational document-oriented NoSQL data storage. This storage service is best designed to store very large amounts of semi-structured data (ie JSON documents). It has very good performance, availability and scalability. It will be based on MongoDB.

Create document-oriented Database

Creates a new document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "database_name":"myDocumentDatabase"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /doc/databases

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Body entity	String	ID (name) of the database

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Database Created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
409	Database already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Document-oriented Database

Drops an existing document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database to be deleted

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Document-oriented Database Collections

Gets the list of collections (catalog) of a given document-oriented database.

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "collections":[
    "myCollection",
    "myCollection2"
  ]
}

Request

Request URL: GET /doc/databases/<database_name>/collections

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the collections of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Document-oriented Database Views

Gets the list of views of a given document-oriented database.

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/views HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "views":[
    "myView1",
    "myView"
  ]
}

Request

Request URL: GET /doc/databases/<database_name>/views

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the views of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Document-oriented Collection

Creates a collection in a given document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "name":"myCollection",
  "options":{
    "size":5242880,
    "max":5000
  }
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /doc/databases/<database_name>/collections

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
name	Yes	Body entity	ID String	ID (name) of the collection
options	No	Body entity	JSON Object	Configuration options for creating a capped collection or for preallocating space in a new collection. For more information of the options see the MongoDB documentation.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Collection created
400	Bad request. There are errors in the specification of the collection
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
409	Collection already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Document-oriented Collection

Drops an existing collection of a given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/collections/<collection_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or collection) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Document-oriented View

Creates a view in a given document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/views HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "view_name":"myView",
  "source_collection":"myCollection",
  "pipeline":[
    {
      "$project":{
        "_id":0,
        "fullname":{
          "$concat":[
            "$FirstName",
            " ",
            "$LastName"
          ]
        }
      }
    }
  ]
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /doc/databases/<database_name>/views

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
view_name	Yes	Body entity	ID String	ID (name) of the view.
source_collection	Yes	Body entity	ID String	ID (name) of the collection the view is based on.
pipeline	Yes	Body entity	Json array	Schema of the view. The exact schema definition format will be specified at a later time.
options	No	Body entity	JSON Object	Configuration options for creating the view. The only existing option is the colation. For more information of the options see the MongoDB documentation.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	View created
400	Bad request. There are errors in the specification of the view
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
409	View already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Document-oriented View

Drops an existing view of a given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/views/myView HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/views/<view_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
view_name	Yes	Resource	String	Identifier for the targeted view

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or view) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Alter Document-oriented View

Alters a view definition in a given document-oriented database. It is a full redefinition of the view, so it's similar to drop and create it again.

PUT https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/views/myView HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "source_collection":"myCollection",
  "pipeline":[
    {
      "$project":{
        "_id":0,
        "fullname":{
          "$concat":[
            "$FirstName",
            " ",
            "$LastName"
          ]
        }
      }
    }
  ]
}

HTTP/1.1 200 OK

Request

Request URL: PUT /doc/databases/<database_name>/views/<view_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
view_name	Yes	Resource	String	Identifier for the targeted view
source_collection	Yes	Body entity	ID String	ID (name) of the collection the view is based on.
pipeline	Yes	Body entity	Json array	Schema of the view. The exact schema definition format will be specified at a later time.
options	No	Body entity	JSON Object	Configuration options for creating the view. The only existing option is the colation. For more information of the options see the MongoDB documentation.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Ok. View altered.
400	Bad request. There are errors in the specification of the alteration of the view
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or view) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Document-oriented Index

Creates a index in a collection of a given document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/indexes HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "index_name":"myIndex",
  "keys":{
    "score":1,
    "price":1
  },
  "options":{
    "collation":{
      "locale":"fr"
    }
  }
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /doc/databases/<database_name>/collections/<collection_name>/indexes

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
index_name	Yes	Body entity	ID String	ID (name) of the index
keys	Yes	Body entity	JSON object	Contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1. MongoDB supports several different index types including text, geospatial, and hashed indexes.
options	No	Body entity	JSON object	Contains a set of options that controls the creation of the index. See MongoDB documentation for details about the index.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Index created
400	Bad request. There are errors in the specification of the index
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or collection) not found
409	Index already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Document-oriented Index

Drops an existing index of a collection of given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/indexes/myIndex HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/collections/<collection_name>/indexes/<index_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
index_name	Yes	Resource	String	Identifier for the targeted index

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, collection or index) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Insert Document-oriented Documents

Inserts document a document or a set of documents in a collection in a given document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "document":[
    {
      "Name":"John",
      "Email":"[email protected]",
      "Age":32
    },
    {
      "Name":"Mary",
      "Email":"[email protected]",
      "Age":41
    }
  ]
}

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
  "n_inserted":2
}

Request

Request URL: POST /doc/databases/<database_name>/collections/<collection_name>/documents

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
document	Yes	Body entity	JSON documet or array of documents	Document(s) to be inserted.
ordered	No	Body entity	If true, perform an ordered insert of the documents in the array, and if an error occurs with one of documents, MongoDB will return without processing the remaining documents in the array. If false, perform an unordered insert, and if an error occurs with one of documents, continue processing the remaining documents in the array. Defaults to true.

Response

Returns a status code and the number of inserted documents in case of success, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Documents inserted
400	Bad request. There are errors in the specification of document values
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or collection) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete Document-oriented document

Deletes a document in a collection of given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents/507f1f77bcf86cd799439011 HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/collections/<collection_name>/documents/<doc_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
doc_id	Yes	Resource	String	The ID of the document

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or collection) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete Document-oriented documents

Deletes a set of documents in a collection of given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "filter":{
    "Age":{
      "$gt":10,
      "$lt":18
    }
  }
}

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/collections/<collection_name>/documents

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
filter	No	Body entity	JSON object	Specifies selection filter using query operators, using the form { : { : }, ... }. To return all documents in a collection, omit this parameter or pass an empty document ({}). More information on MongoDB documentation. [(https://docs.mongodb.com/manual/tutorial/query-documents/)]

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
404	Resource (database or collection) not found
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Merge Document-oriented document

Updates an existing document updating the selected properties and keeping the values of the not selected ones.

PATCH https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents/507f1f77bcf86cd799439011 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "update":{
    "$set":{
      "size.uom":"cm",
      "status":"P"
    },
    "$currentDate":{
      "lastModified":true
    }
  }
}

HTTP/1.1 200 OK

Request

Request URL: PATCH /doc/databases/<database_name>/collections/<collection_name>/documents/<doc_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
doc_id	Yes	Resource	String	The ID of the document
update	Yes	Body entity	JSON object	Update operators: $set, $inc, $currentDate, ... ). For more information see "update operators" in MongoDB documentation.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, collection or document) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Merge Document-oriented documents

Updates a set of documents updating the selected properties and keeping the values of the not selected ones.

PATCH https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "update":{
    "$set":{
      "size.uom":"cm",
      "status":"P"
    },
    "$currentDate":{
      "lastModified":true
    }
  },
  "filter":{
    "qty":{
      "$lt":50
    }
  }
}

HTTP/1.1 200 OK

Request

Request URL: PATCH /doc/databases/<database_name>/collections/<collection_name>/documents

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
update	Yes	Body entity	JSON object	Update operators: $set, $inc, $currentDate, ... ). For more information see "update operators" in MongoDB documentation.
filter	No	Body entity	JSON object	Specifies selection filter using query operators, using the form { : { : }, ... }. To return all documents in a collection, omit this parameter or pass an empty document ({}). More information on MongoDB documentation. [(https://docs.mongodb.com/manual/tutorial/query-documents/)]

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or collection) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Update Document-oriented document

Updates an existing document updating the selected properties and deleting the values of the not selected ones. It is equivalent to a delete+insert. It just keeps the _id field.

PUT https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents/507f1f77bcf86cd799439011 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "update":{
    "$set":{
      "size.uom":"cm",
      "status":"P"
    },
    "$currentDate":{
      "lastModified":true
    }
  }
}

HTTP/1.1 200 OK

Request

Request URL: PUT /doc/databases/<database_name>/collections/<collection_name>/documents/<doc_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
doc_id	Yes	Resource	String	The ID of the document
update	Yes	Body entity	JSON object	Update operators: $set, $inc, $currentDate... ). For more information see "update operators" in MongoDB documentation.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, collection or document) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Query Document-oriented document

Queries a collection of a document-oriented database with a known document identifier.

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents/507f1f77bcf86cd799439011?projection=%5B%22Name%22%3A1%2C%22Age%22%3A0%5D HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "document":{
    "Name":"John"
  }
}

Request

Request URL: GET /doc/databases/<database_name>/collections/<collection_name>/documents/<doc_id>?projection=<projection>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
doc_id	Yes	Resource	String	The ID of the document
projection	No	Query	JSON Object	The projection parameter determines which fields are returned in the matching documents. The projection parameter takes a document of the following form: { field1: , field2: ... }. If not specified, all the colums in the collection/view will be returned.

Response

Returns a status code. In case of success it also returns the selected document, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, collection or document) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Query Document-oriented documents

Queries a collection or view of a document-oriented database

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/collections/myCollection/documents??projection=%5B%22Name%22%3A1%2C+%22Age%22%3A1%5D&filter=Age%3A%7B%24gt%3A10%2C%24lt%3A18%7D&skip=3&limit=20 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "documents":[
    {
      "Name":"John",
      "Age":12
    },
    {
      "Name":"Ann",
      "Age":15
    }
  ]
}

Request

Request URL (collections): GET /doc/databases/<database_name>/collections/<collection_name>/documents?projection=<projection>&filter=<filter>&skip=<skip>&limit=<limit>

Request URL (views): GET /doc/databases/<database_name>/views/<view_name>/documents?projection=<projection>&filter=<filter>&skip=<skip>&limit=<limit>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
collection_name	Yes	Resource	String	The ID/Name of the collection
view_name	Yes	Resource	String	The ID/Name of the view
projection	No	Query	JSON Object	The projection parameter determines which fields are returned in the matching documents. The projection parameter takes a document of the following form: { field1: , field2: ... }. If not specified, all the colums in the collection/view will be returned.
filter	No	Query	JSON object	Specifies selection filter using query operators, using the form { : { : }, ... }. To return all documents in a collection, omit this parameter or pass an empty document ({}). More information on MongoDB documentation. [(https://docs.mongodb.com/manual/tutorial/query-documents/)]
skip	No	Query	Integer	Specifies the first number of results to be ignored (not returned). Used usually for pagination.
limit	No	Query	Integer	Specifies the maximum number of results to be returned

Response

Returns a status code. In case of success it also returns a list of the selected documents, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or collection) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Document-oriented Role

Creates a role in a given document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/roles HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "role":{
    "role":"myRole"
  }
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /doc/databases/<database_name>/roles

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
role	Yes	Body entity	JSON object	A document containing the name of the role and the role definition. It must specify the name of the role. For more detailed information see role definition of MongoDB.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Role created
400	Bad request. There are errors in the specification of the role
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
409	Role already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Document-oriented Role

Drops an existing role of a given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/roles/myRole HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
role_name	Yes	Resource	String	Identifier for the targeted role

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Document-oriented Roles

Gets the list of roles (catalog) of a given document-oriented database.

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/roles HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: GET /doc/databases/<database_name>/roles

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the roles of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Create Document-oriented User

Creates a user in a given document-oriented database.

POST https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/users HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "user":"anotherUser",
  "pwd":"anotherUserPwd"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /doc/databases/<database_name>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user	Yes	Body entity	ID String	ID (name) of the user
pwd	Yes	Body entity	Password of the user

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	User created
400	Bad request. There are errors in the specification of the user
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
409	User already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Document-oriented User

Drops an existing user of a given document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/users/anotherUser HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or user) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Document-oriented Users

Gets the list of users (catalog) of a given document-oriented database.

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/users HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "users":[
    {
      "_id":"myDocumentDatabase.anotherUser",
      "user":"anotherUser",
      "db":"myDocumentDatabase",
      "roles":[

      ]
    },
    {
      "_id":"myDocumentDatabase.anotherUser2",
      "user":"anotherUser2",
      "db":"test",
      "roles":[

      ]
    }
  ]
}

Request

Request URL: GET /doc/databases/<database_name>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the users of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Add Document-oriented role to user

Grants the privileges of a role to a given user in a document-oriented database.

PUT https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/users/anotherUser/roles/editor HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: PUT /doc/databases/<database_name>/users/<user_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user
role_name	Yes	Resource	String	Identifier for the targeted role

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Delete Document-oriented role to user

Revokes the privileges of a role to a given user in a document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/users/anotherUser/roles/editor HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/databases/<database_name>/users/<user_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user
role_name	Yes	Resource	String	Identifier for the targeted role

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Grant permissions Document-oriented

Grants permissions to a role in a document-oriented database.

PUT https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/roles/editor HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "privileges":[
    {
      "resource":{
        "collection":""
      },
      "actions":[
        "find",
        "createCollection",
        "dbStats",
        "collStats"
      ]
    },
    {
      "resource":{
        "collection":"logs"
      },
      "actions":[
        "insert"
      ]
    },
    {
      "resource":{
        "collection":"data"
      },
      "actions":[
        "insert",
        "update",
        "remove",
        "compact"
      ]
    },
    {
      "resource":{
        "collection":"system.js"
      },
      "actions":[
        "find"
      ]
    }
  ]
}

HTTP/1.1 200 OK

Request

Request URL : PUT /doc/databases/<database_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
role_name	Yes	Resource	String	Identifier for the targeted role
privileges	Yes	Body entity	JSON array	List of privileges and scope to be granted. More information on MongoDB documentation. [(https://docs.mongodb.com/v3.0/reference/system-roles-collection/#admin.system.roles.privileges)]

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Revoke permissions Document-oriented

Revokes permissions to a role or user in a document-oriented database.

DELETE https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/roles/editor HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "privileges":[
    {
      "resource":{
        "collection":""
      },
      "actions":[
        "find",
        "createCollection",
        "dbStats",
        "collStats"
      ]
    },
    {
      "resource":{
        "collection":"logs"
      },
      "actions":[
        "insert"
      ]
    },
    {
      "resource":{
        "collection":"data"
      },
      "actions":[
        "insert",
        "update",
        "remove",
        "compact"
      ]
    },
    {
      "resource":{
        "collection":"system.js"
      },
      "actions":[
        "find"
      ]
    }
  ]
}

HTTP/1.1 200 OK

Request

Request URL : DELETE /doc/databases/<database_name>/roles/<role_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
role_name	Yes	Resource	String	Identifier for the targeted role
privileges	Yes	Body entity	JSON array	List of privileges and scope to be revoked. More information on MongoDB documentation. [(https://docs.mongodb.com/v3.0/reference/system-roles-collection/#admin.system.roles.privileges)]

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, user or role) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Query user pemissions Document-oriented

Gets the list of permissions of a user of a given document-oriented database.

GET https://api.vfos.com:7777/3.0/doc/databases/myDocumentDatabase/users/anotherUser HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user":{
    "_id":"myDocumentDatabase.anotherUser",
    "user":"anotherUser",
    "db":"myDocumentDatabase",
    "roles":[

    ]
  }
}

Request

Request URL: GET /doc/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user

Response

Returns a status code. In case of success it also returns a JSON document with the user and the roles it has and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database or user) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Time-series Storage

This section describes functionalities regarding time-series data storage.

It is based on InfluxDB database management system.

Create Time-series Database

Creates a new time-series database.

POST https://api.vfos.com:7777/3.0/tser/databases HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "database_name":"myTimeseriesDatabase"
}

HTTP/1.1 200 OK

Request

Request URL: POST /tser/databases

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Body entity	String	ID (name) of the database

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Time-series Database

Drops an existing time-series database.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /tser/databases/<database_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database to be deleted

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Measurements

Gets the list of measurements (catalog) of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/measurements HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "name":"measurements",
          "columns":[
            "name"
          ],
          "values":[
            [
              "cpu"
            ],
            [
              "hardisk"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/measurements?measurement=<measurement>&filter=<filter>&offset=<offset>&limit=<limit>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurment	No	Query	String	Regular expression to filter the measurements by their names.
filter	No	Query	String	Filter of the measurements by the tags values. It conforms the WHERE clause of the statement. You can get more information about this on SHOW MEASUREMENT statement information on the InfluxDB documentation.
offset	No	Query	Integer	Specifies the first number of measurments to be ignored (not returned). Used usually for pagination. Must be used with limit.
limit	No	Query	Integer	Specifies the maximum number of measurments to be returned

Response

Returns a status code. In case of success it also returns a catalog (list) of the measurements of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Tag keys

Gets the list of tag keys of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/tag_keys HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "name":"cpu",
          "columns":[
            "tagKey"
          ],
          "values":[
            [
              "host"
            ],
            [
              "region"
            ]
          ]
        },
        {
          "name":"hardisk",
          "columns":[
            "tagKey"
          ],
          "values":[
            [
              "host"
            ],
            [
              "region"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/tag_keys?measurement=<measurement>&filter=<filter>&offset=<offset>&limit=<limit>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurment	No	Query	String	Name of the measurement
filter	No	Query	String	Filter of the tag_key by the tags values. It conforms the WHERE clause of the statement. You can get more information about this on SHOW TAG KEYS statement information on the InfluxDB documentation.
offset	No	Query	Integer	Specifies the first number of measurments to be ignored (not returned). Used usually for pagination. Must be used with limit.
limit	No	Query	Integer	Specifies the maximum number of measurments to be returned

Response

Returns a status code. In case of success it also returns a list of the tag keys of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Tag values

Gets the list of tag values of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/tag_values?keys=host HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "name":"cpu",
          "columns":[
            "key",
            "value"
          ],
          "values":[
            [
              "host",
              "serverA"
            ]
          ]
        },
        {
          "name":"hardisk",
          "columns":[
            "key",
            "value"
          ],
          "values":[
            [
              "host",
              "serverA"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/tag_values?measurement=<measurement>&keys=<keys>&filter=<filter>&offset=<offset>&limit=<limit>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurment	No	Query	String	Name of the measurement
keys	Yes	Query	String	Key spcification. It supports specifying a single tag key, a regular expression, and multiple tag keys.
filter	No	Query	String	Filter of the tag_values by the tags values. It conforms the WHERE clause of the statement. You can get more information about this on SHOW TAG VALUES statement information on the InfluxDB documentation.
offset	No	Query	Integer	Specifies the first number of measurments to be ignored (not returned). Used usually for pagination. Must be used with limit.
limit	No	Query	Integer	Specifies the maximum number of measurments to be returned

Response

Returns a status code. In case of success it also returns a list of the tag values of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Field keys

Gets the list of field keys of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/field_keys HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "name":"cpu",
          "columns":[
            "fieldKey",
            "fieldType"
          ],
          "values":[
            [
              "value",
              "float"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/field_keys?measurement=<measurement>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurment	No	Query	String	Name of the measurement

Response

Returns a status code. In case of success it also returns a list of the field keys of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Series

Gets the list of series of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/series HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "columns":[
            "key"
          ],
          "values":[
            [
              "cpu,host=serverA,region=us_west"
            ],
            [
              "hardisk,host=serverA,region=us_west"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/series?measurement=<measurement>&filter=<filter>&offset=<offset>&limit=<limit>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurment	No	Query	String	Name of the measurement
filter	No	Query	String	Filter of the series by the tags values. It conforms the WHERE clause of the statement. You can get more information about this on SHOW SERIES statement information on the InfluxDB documentation.
offset	No	Query	Integer	Specifies the first number of measurments to be ignored (not returned). Used usually for pagination. Must be used with limit.
limit	No	Query	Integer	Specifies the maximum number of measurments to be returned

Response

Returns a status code. In case of success it also returns a list of the series of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Retention Policies

Gets the list of Retention Policies (catalog) of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/retention_policies HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "columns":[
            "name",
            "duration",
            "shardGroupDuration",
            "replicaN",
            "default"
          ],
          "values":[
            [
              "autogen",
              "0s",
              "168h0m0s",
              1,
              true
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/retention_policies

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the retention policies of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Database Continuous Queries

Gets the list of Continuous Queries (catalog) of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/continuous_queries HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "name":"_internal",
          "columns":[
            "name",
            "query"
          ]
        },
        {
          "name":"test",
          "columns":[
            "name",
            "query"
          ],
          "values":[
            [
              "cq_basic",
              "CREATE CONTINUOUS QUERY cq_basic ON test BEGIN SELECT mean(passengers) INTO test.autogen.average_passengers FROM test.autogen.bus_data GROUP BY time(1h) END"
            ]
          ]
        },
        {
          "name":"mydb",
          "columns":[
            "name",
            "query"
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/continuous_queries

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the continuous queries of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Insert data in a Time-series database

Inserts data in a given time-series database. The data is composed on the following elements:

POST https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/measurements/myMeasurement/series HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "values":[
    {
      "tagSet":[
        "train_id=tr1280"
      ],
      "fieldSet":[
        "passengers=5,complaints=9"
      ],
      "time":1422568543702900257
    },
    {
      "tagSet":[
        "train_id=tr1280"
      ],
      "fieldSet":[
        "passengers=8,complaints=9"
      ]
    },
    {
      "tagSet":[
        "train_id=tr1281"
      ],
      "fieldSet":[
        "passengers=3,complaints=1"
      ]
    },
    {
      "tagSet":[
        "train_id=tr1282"
      ],
      "fieldSet":[
        "passengers=4,complaints=2"
      ]
    }
  ]
}

HTTP/1.1 201 CREATED

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurement_name	Yes	Resource	String	The ID/Name of the measurement
fieldSet	Yes	Body entity	Key-value field set	Field set. List of 1 to N fieldField-fieldValue pairs.
tagSet	No	Body entity	Key-value tag set	Tag set. List of 0 to N tagField-tagValue pairs.
time	No	Body entity	Timestamp	Timestamp. If not specified, system timestamp will be inserted

Request

Request URL: POST /tser/databases/<database_name>/measurements/<measurement_name>/series

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurement_name	Yes	Resource	String	The ID/Name of the measurement
values	Yes	Body entity	JSON object	List of values. The values must have fieldSet and may have tagSet and time.

Response

Returns a status code, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
201	Rows inserted
400	Bad request. There are errors in the specification of the request
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Time-series Measurement

Drops an existing measurement of a given time-series database.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/measurements/myMeasurement HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /tser/databases/<database_name>/measurements/<measurement_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurement_name	Yes	Resource	String	The ID/Name of the measurement

Response

Returns a status code and in case of error, an error message in the response body. Note that it does not return an error if the measurement or the database does not exist.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete Time-series points

Deletes a set of points of given time-series database.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/series HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "filter":"Name = 'John' and time smaller than '2016-01-01'",
  "measurement":"train_data",
  "drop_series":1
}

HTTP/1.1 200 OK

Request

Request URL: DELETE /tser/databases/<database_name>/series

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
filter	No*	Body entity	String	Filter of the rows. It will be an string specifying the WHERE clause. If not specified, all the rows will be deleted. The condition may include only tags and time.
measurement	No*	Body entity	String	Name of the measurement. If not specified the filter will be applied to all measurements in the database.
drop_series	No	Body entity	Integer	1 means that the statement must also drop the series from the index. 0 means it must just delete the points. The default value is 1.

Note: At least one of filter and measurement must be specified.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Query Time-series measurement

Queries a measurement of a time-series database

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/measurements/myMeasurement/train_data/series?columns=%5B%22max%28complaints%29%22%5D&filter=train_id%3D%27tr1280%27 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "name":"train_data",
          "columns":[
            "time",
            "max"
          ],
          "values":[
            [
              "2017-09-04T08:39:15.3504908Z",
              9
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL : GET /tser/databases/<database_name>/measurements/<measurement_name>/series?colums=<colums>&filter=<filter>&skip=<skip>&sskip=<sskip>&limit=<limit>&slimit=<slimit>&group_by=<group_by>&order_by=<order_by>&time_zone=<time_zone>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurement_name	Yes	Resource	String	The ID/Name of the measurement
columns	No	Query	JSON Object	Column list. The columns can be real column names or aggregation expressions (MAX, MIN, AVG...). If not specified, all the colums in the table will be returned.
filter	No	Query	String	Filter of the points. It will be an string specifying the WHERE clause of the select. If not specified, all the points will be selected.
skip	No	Query	Integer	Specifies the first number of points to be ignored (not returned). Used usually for pagination. Must be used with limit.
sskip	No	Query	Integer	Specifies the first number of points to be ignored (not returned). Used usually for pagination. Must be used with slimit.
limit	No	Query	Integer	Specifies the maximum number of points to be returned
slimit	No	Query	Integer	Specifies the maximum number of series to be returned
group_by	No	Query	String	Creates a group for each combination of column expressions. It will be an string specifying the GROUP BY clause of the select.
order_by	No	Query	String	Order criteria of the points. It will be an string specifying the ORDER BY clause of the select.
time_zone	No	Query	String	The tz() clause includes the UTC offset or, if applicable, the UTC Daylight Savings Time (DST) offset to the query�s returned timestamps. The time_zone parameter follows the TZ syntax in the Internet Assigned Numbers Authority time zone database.

Response

Returns a status code. In case of success it also returns a list of the selected points, and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Time-series Continuous Query

Creates a new time-series continuous query.

POST https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/measurements/myMeasurement/continuous_querys HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "continuous_query_name":"myTimeseriesContinuousQuery"
}

HTTP/1.1 200 OK

Request

Request URL: POST /tser/databases/<database_name>/measurements/<measurement_name>/continuous_querys

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurement_name	Yes	Resource	String	The ID/Name of the measurement
continuous_query_name	Yes	Body entity	ID String	ID (name) of the continuous query
function	Yes	Body entity	String	Function to be performed. More information on Continuous Query syntax in influxDB documentation.
destination_measurement	Yes	Body entity	String	Name of the destination measurement
filter	No	Body entity	String	Condition. It conforms the WHERE clause of the statement.
group_by	Yes	Body entity	String	Grouping expression. It will be an string specifying the GROUP BY clause of the select.
resample_every	No	Body entity	String	CQs execute at the same interval as the 'resample_every' interval, and they run at the start of InfluxDB�s preset time boundaries.
resample_for	No	Body entity	String	When the CQ executes, it runs a single query for the time range between now() and now() minus the 'resample_for' interval. If the 'resample_for' interval is two hours and the current time is 17:00, the query�s time range is between 15:00 and 16:59.999999999.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Time-series Continuous Query

Drops an existing time-series continuous query.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/measurements/myMeasurement/continuous_querys/myContinuousQuery HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /tser/databases/<database_name>/measurements/<measurement_name>/continuous_querys/<continuous_query_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
measurement_name	Yes	Resource	String	The ID/Name of the measurement
continuous_query_name	Yes	Resource	String	The ID/Name of the continuous query

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Time-series Retention Policy

Creates a new time-series retention policy.

POST https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/retention_policies HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "retention_policy_name":"myTimeseriesRetentionPolicy"
}

HTTP/1
.1 200 OK

Request

Request URL: `POST /tser/databases//retention_policies

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
retention_policy_name	Yes	Body entity	ID String	ID (name) of the retention policy
duration	Yes	Body entity	String	Determines how long InfluxDB keeps the data. The 'duration' is a duration literal or INF (infinite). The minimum duration for a retention policy is one hour and the maximum duration is INF.
replication	Yes	Body entity	Integer	Determines how many independent copies of each point are stored in the cluster, where 'replication' is the number of data nodes.

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.

Drop Time-series Retention Policy

Drops an existing time-series retention policy.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/retention_policies/myRetentionPolicy HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /tser/databases/<database_name>/retention_policies/<retention_policy_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
retention_policy_name	Yes	Resource	String	The ID/Name of the retention policy

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create Time-series User

Creates a user in a given time-series database.

POST https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/users HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "new_user_name":"anotherUser",
  "new_user_password":"anotherUserPwd"
}

HTTP/1.1 200 OK

Request

Request URL: POST /tser/databases/<database_name>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
new_user_name	Yes	Body entity	ID String	ID (name) of the user
new_user_password	Yes	Body entity	Password of the user

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
400	Bad request. There are errors in the specification of the user
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
409	User already exists
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Drop Time-series User

Drops an existing user of a given time-series database.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/users/anotherUser HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /tser/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Time-series Users

Gets the list of users (catalog) of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/users HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "columns":[
            "user",
            "privilege"
          ],
          "values":[
            [
              "user1",
              "READ"
            ],
            [
              "user2",
              "WRITE"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database

Response

Returns a status code. In case of success it also returns a catalog (list) of the users of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Database not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Grant permissions to Time-series user

Grants permissions to a user in a time-series database.

PUT https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/users/anotherUser HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "permission":"READ"
}

HTTP/1.1 200 OK

Request

Request URL : PUT /tser/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user
permission	Yes	Body entity	JSON Object	Permission to be granted. It must be one of: READ, WRITE, ALL

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, user) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Revoke permissions to Time-series user

Revokes permissions to a user in a time-series database.

DELETE https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/users/anotherUser HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "permission":"READ"
}

HTTP/1.1 200 OK

Request

Request URL : DELETE /tser/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user
permission	Yes	Body entity	JSON Object	Permission to be revoked. It must be one of: READ, WRITE, ALL

Response

Returns a status code and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource (database, user) not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request. It is equivalent to a delete+insert.

Query user permissions to Time-series user

Gets the list of permissions of a user of a given time-series database.

GET https://api.vfos.com:7777/3.0/tser/databases/myTimeseriesDatabase/users/anotherUser HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "results":[
    {
      "statement_id":0,
      "series":[
        {
          "columns":[
            "database",
            "privilege"
          ],
          "values":[
            [
              "MYTIMESERIESDATABASE",
              "READ"
            ]
          ]
        }
      ]
    }
  ]
}

Request

Request URL: GET /tser/databases/<database_name>/users/<user_name>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
database_name	Yes	Resource	String	The ID/Name of the database
user_name	Yes	Resource	String	ID (name) of the user

Response

Returns a status code. In case of success it also returns a catalog (list) of the permissions and scope of the database and in case of error, an error message in the response body.

Common status codes returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	User not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Data Transformation

Invoke Transformation

The RESTful interface Invoke Transformation transforms the input data and returns the transformed data as output according to the rules implemented in its functional implementation by calling the transformation engine.

Input and output data can only follow the schema in which the transformation is based upon, eg a transformation csv2json will only accept CSV files (formatted as dictated by the transformation rules) and will only produce a JSON file structured following the specifications of the transformation package.

POST http://dev.vfos.eu/transformation/engines/<ID>/transformation HTTP/1.1
Content-Type: application/xml

<transformation>
 <engineId>fromTardyPress</engineId>
 <engineVersion>1.4</engineVersion>
 <sourceFormat>CSV</sourceFormat>
 <targetFormat>XML</targetFormat>
 <dataIn><![CDATA[name;temperature;pressure|\n|clutch1;63.1;600|\n|clutch2;61.7;586|\n|clutch3;59.7;614|\n|clutch4;64.1;603|\n|]]></dataIn>
</transformation>

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

<transformation>
  <engineId>fromTardyPress</engineId>
  <engineVersion>1.4</engineVersion>
  <sourceFormat>CSV</sourceFormat>
  <targetFormat>XML</targetFormat>
  <dataIn><![CDATA[
   {
     "machine": "machine1",
     "company": "Tardy",
     "measures": [{
         "name": "clutch1",
         "temp": "63.1",
         "pres": "600"
       },{
         "name": "clutch2",
         "temp": "61.7",
         "pres": "586"
       },{
         "name": "clutch3",
         "temp": "59.7",
         "pres": "614"
       },{
         "name": "clutch4",
         "temp": "64.1",
         "pres": "603"
       }]
   }
  ]]></dataIn>
</transformation>

Request

Request URL: POST http://dev.vfos.eu/transformation/engines/<ID>/transformation?session=userToken

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
engineId	Yes	Resource	String	ID of the engine to execute
userToken	Yes	Query	String	The userToken propagated through all requests
object	Yes	Body entity	Json Array	A serialised JSON object to transform, embedded in a wrapper

Response

Returns a transformed JSON object in the same format as the input object.

If there is an error during the processing, a message should be returned to specify detailed information and return a HTTP Statuscode.

Common Status Codes Returned

Code	Description
200	Object transformed
403	Insufficient rights
404	Transformation engine not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Data Analytics

The Data Analytics component provides functionalities to derive knowledge, insights, and events from stream- and historic-process-data within the manufacturing domain. The vf-OS developer will be accessing the Data Analytics UI to encapsulate these functionalities in what is called an Analytic Library to be then deployed as part of a vApp. Then, all interactions between the Data Analytics component and any other vf-OS component will always be consumed by the Data Analytics component.

As an example, some of these interactions are the following:

• execute a transformation
• store/retrieve data from the Data Storage
• store/retrieve queries from the Data Storage
• receive stream data from the Messaging and/or Publish/Subscribe

Stream Analytics

This section describes functionalities regarding stream analytics.

General URL

Requests are formatted with the following common variables.

Name	Example	Description
hostname	api.vfos.com	Specifies the server host
port	7777	Specifies the server port
resource_uri	companies/company1	The uri of the resource

The URL is presented in the following format:

https://<hostname>:<port>/streamAnalytics/<resource_uri>

The left part of the URL, up to the resource_uri, is common to all the API endpoints, so it will not be repeated in every interface in this documentation. This should be prefixed to every endpoint.

Content-Type

The content type, for requests as well as for responses will be JSON.

Request and response examples

This guide includes request and response examples. For the shake of clarity examples do not include not relevant information, as the following.

GET /streamAnalytics/companies?pageSize=2& pageNumber=1 HTTP/1.1
Host: localhost:8089
Accept: application/json
Content-Type: application/json
cache-control: no-cache


HTTP/1.1 200 OK
Date: Fri, 06 May 2016 12:21:00 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

Get companies

Returns a list containing data for all companies. For each company we get information about its modules, dataSources, users, etc.

GET http://api.vfos.com:7777/streamAnalytics/companies HTTP/1.1

HTTP/1.1 200 OK

{
    "company": null,
    "listOfCompanies": [
        {
            "dataSources": [],
            "description": "VF_OS",
            "modules": [],
            "name": "VF_OS",
            "users": [
                {
                    "companyName": "VF_OS",
                    "description": "User 1",
                    "name": "User1",
                    "userType": "VF_OS"
                },
                {
                    "companyName": "VF_OS",
                    "description": "User 2",
                    "name": "User2",
                    "userType": "VF_OS"
                }
            ]
        },
        {
            "dataSources": [
                {
                    "companyName": "mass",
                    "description": "dataSource1",
                    . . .
}

Request

Request URL: GET /companies

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a list of the companies with the information about every company and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Companies not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create new company

Adds a new company to the list.

POST http://api.vfos.com:7777/streamAnalytics/companies HTTP/1.1

{
    "name": "{{auxCompany}}",
    "description": "A new company !!!",
    "users": [],
    "dataSources": [],
    "modules": []
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /companies

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
company	Yes	Body	JSON Object	Company data.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
201	Company created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Companies not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate all companies

Gets the result of validating all companies. A company is valid when its modules, datasources, users and thresholds are valid (have good values for every required field).

GET http://api.vfos.com:7777/streamAnalytics/companies/valid HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "validationResult": {
        "valid": false,
        "messages": [
            "DeltaPressionGeneralRefrigerator:  unknown token"
        ]
    },
    "currentState": null
}

Request

Request URL: GET /companies/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Companies not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get company

Returns information for a specific company (dataSources, modules, users, etc).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany HTTP/1.1

HTTP/1.1 200 OK
{
    "company": {
        "dataSources": [
            {
                "companyName": "myCompany",
                "description": "dataSource1",
                "fields": [
                    {
                        "dataSourceName": "ds2",
                        "companyName": "myCompany",
                        "description": "Reading machine id unique",
                        "fieldClass": "KEY",
                        "name": "pp1",
                        "type": "STRING"
                    },
                    . . .

Request

Request URL: GET /companies/<companyId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company

Response

Returns a status code. In case of success it also returns data with the information about the company and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Updates a company

Updates data values in a company. The new values are provided in the request body.

PUT http://api.vfos.com:7777/streamAnalytics/companies/myCompany HTTP/1.1
Content-Type: application/json; charset=utf-8


{
    "name": "myCompany",
    "description": "Updated Description ...!",
    "dataSources": null,
    "modules": null
}

HTTP/1.1 200 OK

Request

Request URL: PUT /companies/<companyId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
company	No	Body	JSON Object	New data values for the company.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Ok. Company updated.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Company not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete company

Deletes a company from the list.

DELETE http://api.vfos.com:7777/streamAnalytics/companies/myCompany HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /streamAnalytics/companies/<companyId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Company not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate a company

Gets the result of validating a specific company. A company is valid when its modules, datasources, users and thresholds are valid (have good values for every required field).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/valid HTTP/1.1

HTTP/1.1 200 OK

{
    "company": null,
    "listOfCompanies": null,
    "module": null,
    "listOfModules": null,
    "dataSource": null,
    "listOfDataSources": null,
    "sentence": null,
    "listOfSentences": null,
    "threshold": null,
    "listOfThresholds": null,
    "user": null,
    "listOfUsers": null,
    "status": {
        "httpStatusCode": "200",
        "errorCode": "200",
        "errorMessage": ""
    },
    "validationResult": {
        "valid": true,
        "messages": [
        ]
    },
    "currentState": null
}

Request

Request URL: GET /companies/<companyId>/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get modules

Returns a list containing data for all modules in the company. The list supports paging.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules  HTTP/1.1

HTTP/1.1 200 OK

{
    "company": null,
    "listOfCompanies": null,
    "module": null,
    "listOfModules": [
        {
            "companyName": "mass",
            "dataSourceNames": [
                "compressorReadings"
            ],
            "fullDataSources": true,
            "dataSources": [
                {
                    "companyName": "mass",
                    "description": "readings with temperature & presures measurements",
                    "fields": [
                        {
                            "dataSourceName": "compressorReadings",
                            "companyName": "mass",
                            "description": "Reading temperature water inlet 2 compressor",
                            "fieldClass": "MEASUREMENT_VALUE",
                            "name": "TR101",
                            "type": "DOUBLE"
                        },
                        . . .
}

Request

Request URL: GET /companies/<companyId>/modules

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a list of the modules in the company, with the information about every module and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Adds a new module to the company

Creates a new module and adds it to the modules in the company.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules HTTP/1.1

{
    "companyName": "myCompany",
    "description": "The aux module",
    "name": "auxModule",
    "status": "UNLOADED"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /companies/<companyId>/modules

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
module	Yes	Body	JSON Object	Module data.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
201	Module created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get module

Returns information for a specific module (dataSources, sentences, thresholds, status...)

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule HTTP/1.1

HTTP/1.1 200 OK

{
    "company": null,
    "listOfCompanies": null,
    "module": {
        "companyName": "myCompany",
        "dataSourceNames": [
            "compressorReadings"
        ],
        "fullDataSources": true,
        "dataSources": [
            {
              . . .

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module

Response

Returns a status code. In case of success it also returns data with the information about the module and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Updates a module

Updates data values in a module. The new values are provided in the request body.

PUT http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule HTTP/1.1

{
    "companyName": "myCompany",
    "description": "AAAAAA",
    "name": "myModule",
    "status": "LOADED"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /companies/<companyId>/modules/<moduleId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module.
module	Yes	Body	JSON Object	New data values for the module.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Ok. Company updated.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete module

Deletes a module from a company.

DELETE http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /streamAnalytics/companies/<companyId>/modules/<moduleId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate module

Gets a module validation status. A module is valid if its dataSources, sentences and thresholds are valid.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/valid HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "validationResult": {
        "valid": true,
        "messages": []
    },
    "currentState": null
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Gets module current state

Returns current state for the module (DEPLOYED, UNDEPLOYED, UNDEPLOYED_WITH_ERRORS...).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/currentState HTTP/1.1

HTTP/1.1 200 OK

{
   . . .
    "currentState": "DEPLOYED"
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/currentState

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module

Response

Returns a status code. In case of success it also returns the current state for the module (in currentState) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Sends command to a module

Send a command (load, unload) to the module.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/commands?command=load   HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: POST /companies/<companyId>/modules/<moduleId>/commands

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module
command	Yes	Query	String	The command to send.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get sentences

Returns a list containing data for all sentences in a module. The list supports paging.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences  HTTP/1.1

HTTP/1.1 200 OK

{
    "company": null,
    "listOfCompanies": null,
    "module": null,
    "listOfModules": null,
    "dataSource": null,
    "listOfDataSources": null,
    "sentence": null,
    "listOfSentences": [
        {
            "alarmName": "EXCESS_TEMPERATURE",
            "companyName": "mass",
            "condition": "(TR7 - TR100 > DeltaWaterTempCal ) AND (TR2 + TR200 < DeltaWaterTempOfGeneralRefrigerator)",
            "dataSourceName": "compressorReadings",
            "description": "",
            "level": "CRITICAL",
            "moduleName": "temperatureAnalysis",
            "name": "AlarmTemperatureCompressorReadings1",
            "status": "STARTED",
            "type": "ALARM_DETECTION"
        },
        . . .

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/sentences

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a list of the sentences in the module, with the information about every sentence and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Adds a new sentence to the module

Creates a new sentence and adds it to the sentences in the module.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences HTTP/1.1

{
    "alarmName": "EXCESO_TEMPERATURA",
    "companyName": "myCompany",
    "condition": "TR101 > ( TR31 + GDeltaTAguaRefrigeradorGeneral ) AND TR7 < ( TR31 + GDeltaTAguaCal )",
    "dataSourceName": "compressorReadings",
    "description": "",
    "level": "CRITICAL",
    "type": "ALARM_DETECTION",
    "moduleName": "myModule",
    "name": "auxSentence"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /companies/<companyId>/modules/<moduleId>/sentences

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module.
sentence	Yes	Body	JSON Object	Sentence data.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
201	Sentence created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get sentence

Returns data for a single sentence from its id (alarm_name, condition, level, status...).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences/mySentence HTTP/1.1

HTTP/1.1 200 OK

{
    "company": null,
    "listOfCompanies": null,
    "module": null,
    "listOfModules": null,
    "dataSource": null,
    "listOfDataSources": null,
    "sentence": {
        "alarmName": "EXCESS_TEMPERATURE",
        "companyName": "mass",
        "condition": "(TR7 - TR100 > DeltaWaterTempCal ) AND (TR2 + TR200 < DeltaWaterTempOfGeneralRefrigerator)",
        "dataSourceName": "compressorReadings",
        "description": "",
        "level": "CRITICAL",
        "moduleName": "temperatureAnalysis",
        "name": "AlarmTemperatureCompressorReadings1",
        "status": "STARTED",
        "type": "ALARM_DETECTION"
    },
    . . .

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/sentences/<sentenceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
sentenceId	Yes	Resource	String	Identifier for the targeted sentence

Response

Returns a status code. In case of success it also returns data with the information about the sentence and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Updates a sentence

Updates data values in a sentence. The new values are provided in the request body.

PUT http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences/mySentence HTTP/1.1

{
    "alarmName": "EXCESO_TEMPERATURA",
    "companyName": "myCompany",
    "dataSourceName": "myDataSource",
    "moduleName": "myModule",
    "name": "mySentence",
    "type": "ALARM_DETECTION"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /companies/<companyId>/modules/<moduleId>/sentences/<sentenceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module.
sentenceId	Yes	Resource	String	Identifier for the targeted sentence.
sentence	No	Body	JSON Object	New data values for the sentence.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Ok. Company updated.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete sentence

Deletes a sentence from a module.

DELETE http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences/mySentence HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /streamAnalytics/companies/<companyId>/modules/<moduleId>/sentences/<sentenceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
sentenceId	Yes	Resource	String	Identifier for the targeted sentence

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Sends command to a sentence

Send a command (run, stop) to the sentence.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences/mySentence/commmands?command=stop HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: POST /companies/<companyId>/modules/<moduleId>/commands

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module.
sentenceId	Yes	Resource	String	Identifier for the targeted sentence.
command	Yes	Query	String	The command to send.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate sentence

Gets a sentence validation status. A sentence is valid if it references a valid dataSource and valid thresholds and the condition is a valid expression.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences/mySentence/valid HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "validationResult": {
        "valid": true,
        "messages": [
            "esper:  ( TR7 - TR100 > DeltaWaterTempCal ) AND ( TR2 + TR200 < DeltaWaterTempOfGeneralRefrigerator ) ",
            "vf-os:  ( TR7 - TR100 > DeltaWaterTempCal ) AND ( TR2 + TR200 < DeltaWaterTempOfGeneralRefrigerator )"
        ]
    },
    "currentState": null
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/sentences/<sentenceId>/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
sentenceId	Yes	Resource	String	Identifier for the targeted sentence

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Gets sentence current state

Returns current state for the sentence (STARTED, STOPPED, DESTROYED, FAILED).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/sentences/mySentence/currentState HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "currentState": "STOPPED"
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/sentences/<mySentence>/currentState

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
sentenceId	Yes	Resource	String	Identifier for the targeted sentence

Response

Returns a status code. In case of success it also returns the current state for the sentence (in currentState) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get thresholds

Returns a list containing data for all thresholds in a module. The list supports paging.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/thresholds  HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "listOfThresholds": [
        {
            "companyName": "mass",
            "description": "Threshold for the water Temperature of General Refrigerator expressed in degrees",
            "moduleName": "temperatureAnalysis",
            "name": "DeltaWaterTempOfGeneralRefrigerator",
            "type": "DOUBLE",
            "value": "67.8"
        },
        {
            "companyName": "mass",
            "description": "CHANGED  !!!!",
            "moduleName": "temperatureAnalysis",
            "name": "DeltaWaterTempCal",
            "type": "DOUBLE",
            "value": "4.55"
        }
    ],
    . . .
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/thresholds

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a list of the thresholds in the module, with the information about every threshold and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Adds a new threshold to the module

Creates a new threshold and adds it to the thresholds in the module.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/thresholds HTTP/1.1

{
    "companyName": "myCompany",
    "description": "",
    "moduleName": "myModule",
    "name": "myThreshold",
    "type": "DOUBLE",
    "value": "100.5"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /companies/<companyId>/modules/<moduleId>/thresholds

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module.
threshold	Yes	Body	JSON Object	threshold data.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
201	Threshold created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get threshold

Returns data for a single threshold from its id (name, type, value...).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/thresholds/myThreshold HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "threshold": {
        "companyName": "myCompany",
        "description": "A simple threshold",
        "moduleName": "myModule",
        "name": "myThreshold",
        "type": "DOUBLE",
        "value": "4.55"
    },
    . . .
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/thresholds/<thresholdId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
thresholdId	Yes	Resource	String	Identifier for the targeted threshold

Response

Returns a status code. In case of success it also returns data with the information about the threshold and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Updates a threshold

Updates data values in a threshold. The new values are provided in the request body.

PUT http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/thresholds/myThreshold HTTP/1.1

{
    "companyName": "myCompany",
    "description": "CHANGED  !!!!",
    "moduleName": "myModule",
    "name": "myThreshold",
    "type": "DOUBLE",
    "value": "4.55"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /companies/<companyId>/modules/<moduleId>/thresholds/<thresholdId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
moduleId	Yes	Resource	String	Identifier for the targeted module.
thresholdId	Yes	Resource	String	Identifier for the targeted threshold.
threshold	No	Body	JSON Object	New data values for the threshold.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Ok. Threshold updated.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete threshold

Deletes a threshold from a module.

DELETE http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/thresholds/myThreshold HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /streamAnalytics/companies/<companyId>/modules/<moduleId>/thresholds/<thresholdId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
thresholdId	Yes	Resource	String	Identifier for the targeted threshold

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate threshold

Gets a threshold validation status. A threshold is valid if its value correspond with its type.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/modules/myModule/thresholds/myThreshold/valid HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "validationResult": {
        "valid": true,
        "messages": [
            ""
        ]
    },
    "currentState": null
}

Request

Request URL: GET /companies/<companyId>/modules/<moduleId>/thresholds/<thresholdId>/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
moduleId	Yes	Resource	String	Identifier for the targeted module
thresholdId	Yes	Resource	String	Identifier for the targeted threshold

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get dataSources

Returns a list containing data for all dataSources in the company. The list supports paging.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/dataSources  HTTP/1.1

HTTP/1.1 200 OK

{
   . . .
    "listOfDataSources": [
        {
            "companyName": "myCompany",
            "description": "dataSource1",
            "fields": [
                {
                    "dataSourceName": "ds2",
                    "companyName": "myCompany",
                    "description": "Reading machine id unique",
                    "fieldClass": "KEY",
                    "name": "pp1",
                    "type": "STRING"
                },
                . . .

Request

Request URL: GET /companies/<companyId>/dataSources

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a list of the dataSources in the company, with the information about every dataSource and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Adds a new dataSource to the company

Creates a new dataSource and adds it to the dataSources in the company.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/dataSources HTTP/1.1

{
    "companyName": "myCompany",
    "description": "a new data source",
    "name": "myDataSource",
    "status": "STOPPED",
    "topic": "TheTopic"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /companies/<companyId>/dataSources

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
dataSource	Yes	Body	JSON Object	DataSource data.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
201	DataSource created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get dataSource

Returns information for a specific dataSource (name, description, fields, status, topic...).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/dataSources/myDataSource HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "dataSource": {
        "companyName": "myCompany",
        "description": "readings with temperature & presures measurements",
        "fields": [
            {
                "dataSourceName": "myDataSource",
                "companyName": "myCompany",
                "description": "Reading temperature water inlet 2 compressor",
                "fieldClass": "MEASUREMENT_VALUE",
                "name": "TR101",
                "type": "DOUBLE"
            },
            . . .

Request

Request URL: GET /companies/<companyId>/dataSources/<dataSourceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
dataSourceId	Yes	Resource	String	Identifier for the targeted dataSource

Response

Returns a status code. In case of success it also returns data with the information about the dataSource and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Updates a dataSource

Updates data values in a dataSource. The new values are provided in the request body.

PUT http://api.vfos.com:7777/streamAnalytics/companies/myCompany/dataSources/myDataSource HTTP/1.1

{
        "companyName": "myCompany",
        "description": "a new data source",
        "name": "myDataSource",
        "status": "STOPPED",
        "topic": "The  NEW   topic"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /companies/<companyId>/dataSources/<dataSourceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
dataSourceId	Yes	Resource	String	Identifier for the targeted dataSource.
dataSource	Yes	Body	JSON Object	New data values for the dataSource.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Ok. DataSource updated.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete dataSource

Deletes a dataSource from a company.

DELETE http://api.vfos.com:7777/streamAnalytics/companies/myCompany/dataSources/myDataSource HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /streamAnalytics/companies/<companyId>/dataSources/<dataSourceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
dataSourceId	Yes	Resource	String	Identifier for the targeted dataSource

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate dataSource

Gets a dataSource validation status. A dataSource is valid if it references a valid topic and has at least three fields (one of type "KEY", one of type "MEASUREMENT_TIMESTAMP" and one of type "MEASUREMENT_VALUE").

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/dataSources/myDataSource/valid HTTP/1.1

HTTP/1.1 200 OK

{
    . . .
    "validationResult": {
        "valid": false,
        "messages": [
            "dataSourceValid: DATA SOURCE (myCompany.myDataSource) hasn´t key defined (class)",
            "dataSourceValid: DATA SOURCE (myCompany.myDataSource) hasn´t measurement timestamp (class)",
            "dataSourceValid: DATA SOURCE (myCompany.myDataSource) hasn´t any defined measure (class) "
        ]
    },
    "currentState": null
}

Request

Request URL: GET /companies/<companyId>/dataSources/<dataSourceId>/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
dataSourceId	Yes	Resource	String	Identifier for the targeted dataSource

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get users

Returns a list containing data for all users in the company. The list supports paging.

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/users  HTTP/1.1

HTTP/1.1 200 OK

{
   . . .
    "listOfUsers": [
        {
            "companyName": "myCompany",
            "description": "usuario 1",
            "name": "user1",
            "userType": "COMPANY"
        }
    ],
    . . .

Request

Request URL: GET /companies/<companyId>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
pageSize	No	Resource	Integer	Number of items in the page
pageNumber	No	Resource	Integer	Page number

Response

Returns a status code. In case of success it also returns a list of the users in the company, with the information about every user and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Adds a new user to the company

Creates a new user and adds it to the users in the company.

POST http://api.vfos.com:7777/streamAnalytics/companies/myCompany/users HTTP/1.1

{
    "companyName": "myCompany",
    "description": "usuario nuevo",
    "name": "newUser",
    "userType": "COMPANY"
}

HTTP/1.1 201 CREATED

Request

Request URL: POST /companies/<companyId>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
user	Yes	Body	JSON Object	User data.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
201	User created
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get user

Returns information for a specific user (company name, name, description, type).

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/users/myUser HTTP/1.1

HTTP/1.1 200 OK

{
  . . .
    "user": {
        "companyName": "myCompany",
        "description": "usuario 1",
        "name": "myUser",
        "userType": "COMPANY"
    },
    . . .
}

Request

Request URL: GET /companies/<companyId>/users/<userId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
userId	Yes	Resource	String	Identifier for the targeted user

Response

Returns a status code. In case of success it also returns data with the information about the user and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Updates a user

Updates data values in a user. The new values are provided in the request body.

PUT http://api.vfos.com:7777/streamAnalytics/companies/myCompany/users/myUser HTTP/1.1

{
    "companyName": "myCompany",
    "description": "UPDATED DESCRIPTION",
    "name": "myUser",
    "userType": "COMPANY"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /companies/<companyId>/users/<userId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company.
userId	Yes	Resource	String	Identifier for the targeted user.
user	Yes	Body	JSON Object	New data values for the user.

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Ok. User updated.
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Delete user

Deletes a user from a company.

DELETE http://api.vfos.com:7777/streamAnalytics/companies/myCompany/users/myUser HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /streamAnalytics/companies/<companyId>/users/<userId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
userId	Yes	Resource	String	Identifier for the targeted user

Response

Returns a status code and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	OK
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Validate user

Gets a user validation status. A user is valid if the user type is one of "VF_OS" or "COMPANY".

GET http://api.vfos.com:7777/streamAnalytics/companies/myCompany/users/myUser/valid HTTP/1.1

HTTP/1.1 200 OK

{
  . . .
    "validationResult": {
        "valid": true,
        "messages": []
    },
    "currentState": null
}

Request

Request URL: GET /companies/<companyId>/users/<userId>/valid

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
companyId	Yes	Resource	String	Identifier for the targeted company
userId	Yes	Resource	String	Identifier for the targeted user

Response

Returns a status code. In case of success it also returns a validation status (in validationResult.valid) and in case of error, an error message in the response body.

Common Status Codes Returned

Code	Description
200	Success
401	Unauthorized. The credentials provided are not valid.
403	Forbidden. The user has not enough privileges to perform this action.
404	Resource not found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

I/O Toolkit

Virtual Factory Input/Output Interface is a set of modules that virtualise factory’s real assets and connect them to their virtualised images in the vf-OS, vf-IO implements Plug-and-Play mechanisms and device drivers for seamless/open access and smart virtualisation of the factory resources; it is composed by devices drivers, API connectors, security and data access. Thus, the vf-IO is composed of the modules that enable connectivity to assets like legacy ERPs or CRMs, CPS’, smart objects or wireless sensor networks.

Enablers Framework

The Enablers Framework (EF) is a component of vf-OS that provides functionalities for integration of different FIWARE Generic Enablers, FIWARE Manufacturing Enablers and vf-OS Enablers. The interfaces provided by these enablers are based on different standards such as NGSI v1/v2, REST, SOAP and RPC. This complicates the task of the developer when integratating such diverse solutions in a vAPP. EF aims to encapsulate these enablers invocation complexity and provide uniform access interface so that service invocation of any enabler can be done in the same way.

Enablers Framework provides a REST interface for registering, querying and accessing enablers' functionalities. It is developed in the scope of the work package 3 (WP3), under tasks T3.1-T3.2.

The external interfaces exposed by Enablers Framework are provided by two service interfaces, Lookup Services and Access Services, with the following base URLs:

• Lookup Services: http://gris.uninova.pt:5917
• Access Services: http://gris.uninova.pt:5918

All request-handler responses are structured with JSend using Prestaul's Node.js library. All responses have a status and a data. Status can be success, fail or error. Data contains the enablers' responses or the error's full description.

Lookup: get all enablers

Retrieve all enablers, associated connection and its available services.

GET /lookup/enablers HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "name":"orion",
      "description":"Publish/Subscribe Context Broker",
      "metadata":{
        "chapter":"Data/Context Management",
        "updated":"2017-03-09"
      },
      "connection":{
        "url":"http://gris.uninova.pt",
        "port":5911,
        "protocol":"NGSIv1",
        "services":[
          {
            "name":"cancelSubscription",
            "description":"Cancels a context subscription.",
            "bodySchema":{
              "type":"object",
              "properties":{
                "subId":{
                  "type":"string"
                }
              },
              "required":[
                "subId"
              ]
            },
            "metadata":{
              "serviceOwner":"FIWARE",
              "updated":"2017-03-09"
            }
          },
          {
            "name":"getTypeInfo",
            "description":"Gets info about about a concrete entity type.",
            "bodySchema":{
              "type":"object",
              "properties":{
                "type":{
                  "type":"string"
                }
              },
              "required":[
                "type"
              ]
            },
            "metadata":{
              "serviceOwner":"FIWARE",
              "updated":"2017-03-09"
            }
          }
        ]
      }
    },
    {
      "name":"aeon",
      "description":"Cloud Messaging",
      "metadata":{
        "chapter":"Data/Context Management",
        "updated":"2017-06-12",
        "version":"0.2.2"
      },
      "connection":{
        "url":"http://gris.uninova.pt",
        "port":5914,
        "protocol":"REST",
        "services":[
          {
            "name":"/entities/:entityId",
            "description":"Get complete information of an specific entity.",
            "urlSchema":{
              "type":"object",
              "properties":{
                "entityId":{
                  "type":"string"
                }
              },
              "required":[
                "entityId"
              ]
            },
            "metadata":{
              "serviceOwner":"FIWARE",
              "updated":"2017-03-09"
            },
            "method":"GET"
          }
        ]
      }
    }
  ]
}

Request

To get all information of the enablers, the request does not use any parameter.

Request URL: GET /enablers

Transfer Parameters

This endpoint does not have any parameters

Response

If the response is successfull a http status code and data with all enablers' details as well as their connections and services is returned. In the case of an error, an http status code and a message with an error description is returned.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "status":"error",
  "message":"connect ECONNREFUSED."
}

Common HTTP Return Codes

Code	Description
200	OK
400	Malformed request
500	Server error

Lookup: retrieve a specific enabler

Retrieve the connection and its services of a specific enabler.

GET /enablers/orion HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "name":"orion",
    "description":"Publish/Subscribe Context Broker",
    "metadata":{
      "chapter":"Data/Context Management",
      "updated":"2017-03-09"
    },
    "connection":{
      "url":"http://gris.uninova.pt",
      "port":5911,
      "protocol":"NGSIv1",
      "services":[
        {
          "name":"getTypeInfo",
          "description":"Gets info about about a concrete entity type.",
          "bodySchema":{
            "type":"object",
            "properties":{
              "type":{
                "type":"string"
              }
            },
            "required":[
              "type"
            ]
          },
          "metadata":{
            "serviceOwner":"FIWARE",
            "updated":"2017-03-09"
          }
        },
        {
          "name":"cancelSubscription",
          "description":"Cancels a context subscription.",
          "bodySchema":{
            "type":"object",
            "properties":{
              "subId":{
                "type":"string"
              }
            },
            "required":[
              "subId"
            ]
          },
          "metadata":{
            "serviceOwner":"FIWARE",
            "updated":"2017-03-09"
          }
        }
      ]
    }
  }
}

Request

It contains connectionName, which is a required URL parameter.

Request URL: GET /enablers/<enablerName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerName	Yes	Resource	string	The name of the enabler

Response

If the response is successful, it returns an http status code and data with enabler's details as well as its connection and available services. In case of an error, it returns an http status code and additionally a message with the error description.

Common HTTP Return Codes

Code	Description
200	OK
400	Malformed request
500	Server error

Lookup: retrieve a service

Retrieve a specific service of one enabler.

GET /enablers/orion/services/getTypeInfo HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "name":"orion",
    "description":"Publish/Subscribe Context Broker",
    "metadata":{
      "chapter":"Data/Context Management",
      "updated":"2017-03-09"
    },
    "connection":{
      "url":"http://gris.uninova.pt",
      "port":5911,
      "protocol":"NGSIv1",
      "services":[
        {
          "name":"getTypeInfo",
          "description":"Gets info about about a concrete entity type.",
          "bodySchema":{
            "type":"object",
            "properties":{
              "type":{
                "type":"string"
              }
            },
            "required":[
              "type"
            ]
          },
          "metadata":{
            "serviceOwner":"FIWARE",
            "updated":"2017-03-09"
          }
        },
        {
          "name":"cancelSubscription",
          "description":"Cancels a context subscription.",
          "bodySchema":{
            "type":"object",
            "properties":{
              "subId":{
                "type":"string"
              }
            },
            "required":[
              "subId"
            ]
          },
          "metadata":{
            "serviceOwner":"FIWARE",
            "updated":"2017-03-09"
          }
        }
      ]
    }
  }
}

Request

Request URL: GET /enablers/<enablerName>/services/<serviceName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerName	Yes	Resource	string	The name of a specific enabler
serviceName	Yes	Resource	string	The name of a specific ervice

Response

If the response is successful, it returns an http status code and data with service's details.

In case of an error, it returns also an http status code and additionally a message with an error description

Common HTTP Return Codes

Code	Description
200	OK
400	Malformed request
500	Server error

Access Services: Invoke Service

Via this route it is possible to invoke one service of a specific enabler.

POST /accessfunctionality/orionv2/getEntity HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "bodyParams":{
    "type":"channel"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
   "status":"success",
   "data":{
      "correlator":"182fdb0c-9863-11e7-946b-0242ac110003",
      "entity":{
         "id":"LED001",
         "type":"LED",
         "switch":{
            "type":"string",
            "value":"0034223456789",
            "metadata":{

            }
         }
      }
   }
}

Request

Request URL: POST /accessfunctionality/<enablerName>/<serviceName>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerName	Yes	Resource	string	Enabler Name
serviceName	Yes	Resource	string	Service Name
bodyParams	No	Body	object	Regular request parameters
urlParams	No	Body	object	REST only. Parameters for the URL.

Response

The response contains the status of invoking the service as well its data. If it returns one error, it will also return the error description.

Common HTTP Return Codes

Code	Description
201	Created
400	Malformed request
500	Server error

Drivers

Basics

Requests are formatted with the following format:

https://vfos.org/api/<vfos_component>/<version>/<objecttype>/

Where the variables are as follows:

Name	Example	Level	Description
version	v1.0	All	Drivers API version
vfos_component	Drivers	All	Module queried
objecttype	Devices	All	Type of object requested
object ID	569ce99e761b8e982d82c978	Existing objects	Specifies the object ID.

This UUID is assigned by the server.

The common return codes are:

Code	Description
200	OK - GET
201	OK - POST/PUT/PATCH
204	OK - DELETE
400	INVALID REQUEST - [POST/PUT/PATCH]
404	NOT FOUND - [*]
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get existing metadata on Drivers

Method to return the endpoint available by the Driver components (REST verbs). Useful for vf-Platform.

GET /api/drivers/v1/Metadata/ HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "verb":"POST",
    "url":"/api/drivers/v1/Logs/",
    "description":"method to subscribe for log reception"
  },
  {
    "verb":"DELETE",
    "url":"/api/drivers/v1/Devices/<device_id>",
    "description":"method to unregister a device"
  }
]

Request

Request URL: GET /api/drivers/v1/Metadata/

Response

Returns an object that describes the endpoint of the components and the data definitions. The description contains a collection of endpoints, objects, device proprietary parameters and sensor proprietary parameters. An endpoint is described with the following attributes

Name	Type	Description
paths	array of objects	list of endpoints (url, description, verb(PUT, GET, POST)
definitions	array of objects	list of definitions of the objects that are used as input or returned by the endpoint
proprietaryDeviceInfo	array	List of proprietary parameters that a specific driver implements and that a user has to provide value when instancing devices of that protocol. Additionally a provides a default value
proprietarySensorInfo	array	List of proprietary parameters that a specific driver implements and that a user has to provide value when instancing sensor of that protocol. Additionally a provides a default value

Log listing

Function to retrieve a driver log between two dates

GET /api/drivers/v1/Logs/ HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "start":2018-07-05,
  "end":"2018-07-07"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "timestamp":"2018-07-05 17:03:12",
    "message": "error on connection"
  },
  {
    "timestamp":"2018-07-05 17:05:12",
    "message": "node is not available"
  }
]

Request

Request URL: POST /api/drivers/v1/Logs/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
start	Yes	Resource	date	specifies a minimum timestamp for the logEntries that should be retrieved
end	Yes	Resource	date	specifies a minimum timestamp for the logEntries that should be retrieved

Response

Returns an array of logEntry objects containing a timestamp and log message object with the log between two dates of the driver component Each logEntry has:

Name	Type	Description
timestamp	date	timestamp when the log was done
message	string	log message

Register Device Configuration

Create a new device configuration to connect to a physical device in the shop-floor. The request must contain the connection parameters in json format.

POST /api/drivers/v1/Devices/ HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "needProcessing":"yes",
  "processingExpression":"2*v + 7",
  "proprietaryParameters":[
    {
      "name":"endpoint",
      "value":"http://shopfloor:8080/sensor1"
    },
    {
      "name":"pinmode",
      "value":2
    }
  ],
  "_did":"17c8uT"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "_id":"67c8uTrE"
}

Request

Request URL: POST /api/drivers/v1/Devices/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
processingExpression	Yes	Body	string	Expression to process data
proprietaryParameters	No	Body	object	A list of proprietary parameters configuration
name	No	Body	string	name of parameter
value	No	Body	string	value of parameter
_did	Yes	Body	string	uid of driver

Response

Returns the 200 response with the id of the newly registered device. If any error, returns 400 error with the error message.

Edit Device Configuration

Changes the configuration of an existing device configuration on a driver component. The request must contain the connection parameters to be updated in json format.

PUT /api/drivers/v1/Devices/67c8uTrE HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "processingExpression":"4*v + 7",
  "proprietaryParameters":[
    {
      "name":"endpoint",
      "value":"http://shopfloor:8080/sensor1"
    },
    {
      "name":"pinmode",
      "value":2
    }
  ],
  "_did":"17c8uT"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /api/drivers/v1/Devices/<deviceId>/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
devideId	Yes	Resource	string	Id of Device
processingExpression	Yes	Body	string	Expression to process data
proprietaryParameters	No	Body	object	A list of proprietary parameters configuration
name	No	Body	string	name of parameter
value	No	Body	string	value of parameter
_did	Yes	Body	string	uid of driver

Response

Returns default HTTP Status Codes for Acknowledgement (200, 400 codes)

Unregister Device

Endpoint to delete an existing device configuration. Once that the device configuration is deleted, the device is no longer registered and components can no longer interact with the device.

DELETE /api/drivers/v1/Devices/67c8uTrE HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /api/drivers/v1/Devices/<deviceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	device id to be unregistered

Response

Returns default HTTP Status Codes for Acknowledgement (200, 400 codes)

Register Sensor

Create a new sensor configuration in an existing device to collect data from or send commands to a specific sensor connected to the device. The request must contain the configuration parameters to connect to the sensor in json format.

POST /api/drivers/v1/Devices/67c8uTrE/Sensors/ HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "name":"temperature",
  "property":{
    "name":"temperature",
    "type":"real",
    "unit":"degrees"
  },
  "events":[
    {
      "type":"sampling",
      "intervalTime":100
    }
  ],
  "historicData":"false",
  "computingExpression":"%v",
  "actuator":"false"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "_id":"00c8a4Yw"
}

Request

Request URL: POST /api/drivers/v1/Devices/<deviceId>/Sensors/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	Device Id
name	Yes	Body	string	name of the sensor
property	Yes	Body	object	physical property measured by the sensor
name	Yes	Body	string	name of the entity the sensors is measuring e.g. temperature, humidity, etc
type	Yes	Body	string	type of value captured by the sensor
unit	Yes	Body	string	unit of the measure captured by the sensor
events	Yes	Body	Array Object	array of events for a suscription
type	Yes	Body	string	type of event (value or sampling)
samplingInterval	Yes	Body	string	sampling interval for events of type sampling
historicData	Yes	Body	string	this sensor will have its data stored in short term database
actuator	Yes	Body	string	This sensor can receive commands
proprietaryParameters	No	Body	object	proprietary parameters of a sensor conguration
name	No	Body	string	name of parameter
value	No	Body	string	value of parameter

Response

Returns the ID of the newly registered sensor

Edit Sensor Configuration

Changes the configuration of existing sensor configuration of a device in a driver component. The request must contain the parameters to be updated in json format.

PUT /api/drivers/v1/Devices/67c8uTrE/Sensors/00c8a4Yw/ HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "name":"sensor1 packaging machine",
  "property":{
    "name":"temperature",
    "type":"real",
    "unit":"degrees"
  },
  "events":[
    {
      "type":"sampling",
      "intervalTime":100
    }
  ],
  "historicData":"true",
  "computingExpression":"%v",
  "actuator":"false"
}

HTTP/1.1 200 OK

Request

Request URL: PUT /api/drivers/v1/Devices/<deviceId>/Sensors/<sensorId>/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	Device Id
sensorId	Yes	Resource	string	Sensor Id
_sid	Yes	Body	string	sensor Id
_did	Yes	Body	string	Device Id
name	Yes	Body	string	name of the sensor
property	Yes	Body	object	physical property measured by the sensor
name	Yes	Body	string	name of the sensor
type	Yes	Body	string	type of value captured by the sensor
unit	Yes	Body	string	unit of the measure captured by the sensor
events	Yes	Body	Array Object	array of events for a suscription
type	Yes	Body	string	type of events (either value or or sampling)
samplingInterval	Yes	Body	string	sampling interval for events of type sampling
historicData	Yes	Body	string	this sensor will have its data stored in short term database
computingExpression	Yes	Body	string	Expression to process data of sensor
actuator	Yes	Body	string	This sensor can receive commands
proprietaryParameters	No	Body	object	proprietary parameters of a sensor conguration
name	No	Body	string	name of parameter
value	No	Body	string	value of parameter

Response

Returns default HTTP Status Codes for Acknowledgement (200, 400 codes)

Delete Sensor Configuration

Endpoint to delete an existing sensor configuration of a device on a driver component. Once the sensor configuration is deleted, it is no longer possible to collect data from or send commands to the sensor.

DELETE /api/drivers/v1/Devices/67c8uTrE/Sensors/00c8a4Yw/ HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /api/drivers/v1/Devices/<deviceId>/Sensors/<sensorId>/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	device id to be unregistered
sensorId	Yes	Resource	string	sensor id to be unregistered

Response

Returns HTTP Status Code 200 if success, and HTTP Status Code 400 if any failure occurs.

Get Device Configuration

Retrieve the configuration of a device that has previously been created. The id of the device is provided in the request URL and the response returns all the device configuration parameters.

GET /api/drivers/v1/Devices/17c8uT HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "name":"Device X",
  "proprietaryParameters":[
    {
      "name":"endpoint",
      "value":"http://shopfloor:8080/sensor1"
    },
    {
      "name":"pinmode",
      "value":2
    }
  ]
}

Request

Request URL: GET /api/drivers/v1/Devices/<deviceId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	device id of the device the configuration info is requested

Response

Returns info about the device

Name	Type	Description
_did	string	id of device
name	string	name of device
processingExpression	string	a string to compute aggregated computation with sensor data of the device
propietaryParameters	Array objects	A list of proprietary parameters of the device

List existing devices

Returns a list of all previously configured devices in a driver component. The request does not take any arguments and it is not possible to apply filters to the request.

GET /api/drivers/v1/Devices/ HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "_id":"6G439Kl",
    "name":"device 1 packaging",
    "numSensors":3,
    "date":"2017-05-21",
    "driver":"OPC UA driver"
  },
  {
    "_id":"f432lfl",
    "name":"device 2 cutting machine",
    "numSensors":1,
    "date":"2017-05-11",
    "driver":"MQTT driver"
  }
]

Request

Request URL: GET /api/drivers/v1/Devices/

Response

Returns collection of registered devices Name | Type | Description --- | --- | --- _did | string | id of device name | string | name of device processingExpression | string | a string to compute aggregated computation with sensor data of the device propietaryParameters | Array objects | A list of proprietary parameters of the device

List sensors by device

Returns a list of all previously configured sensors in a device. The ID of the device is provided in the request URL and the request does not any other arguments.

GET /api/drivers/v1/Devices/6G439Kl/Sensors HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "_id":"s5G439Kl",
    "name":"sensor 1 packaging",
    "events":[
    {
      "type":"sampling",
      "intervalTime":100
    }
  ],
    "historicData":"false",
    "actuator":"false",
    "status":"ok"
  },
  {
    "_id":"s732lfl",
    "name":"sensor 2 packaging",
    "events":[
    {
      "type":"sampling",
      "intervalTime":100
    }
  ],
    "historicData":"true",
    "actuator":"false",
    "status":"fail"
  }
]

Request

Request URL: GET /api/drivers/v1/Devices/<deviceId>/Sensors/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	id of device

Response

Returns a collection of sensors of given device

Name	Type	Description
_sid	Yes	Body
_did	Yes	Body
name	Yes	Body
property	Yes	Body
name	Yes	Body
type	Yes	Body
unit	Yes	Body
events	Yes	Body
type	Yes	Body
samplingInterval	Yes	Body
historicData	Yes	Body
computingExpression	Yes	Body
actuator	Yes	Body
proprietaryParameters	No	Body
name	No	Body
value	No	Body

Check Device Status

Endpoint to verify that the connection of a previously configured device is correct and that there are no errors in the connection to the physical device

GET /api/drivers/v1/Devices/6G439Kl/Status/ HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "name":"device 1 packaging",
  "status":"fail"
}

Request

Request URL: GET /api/drivers/v1/Devices/<deviceId>/Status/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	id of device

Response

Returns the an object such as:

Name	Type	Description
_sid	string	sensor Id
status	string	ok/failure

Get data from sensor

Endpoint to read data from a sensor of a given device. The ID of the device and the ID of the sensor are provided in the request. The response returns a json object with the last data read from the sensor. This endpoint allows vf-OS components to pull data from a device.

GET /api/drivers/v1/Devices/6G439Kl/Sensors/s5G439Kl/Data HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": 45.32,
  "unit": "degrees",
  "timestamp": "2017-06-07"
}

Request

Request URL: GET /api/drivers/v1/Devices/<deviceId>/Sensors/<sensorId>/Data

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	id of device
sensorId	Yes	Resource	string	id of sensor

Response

Returns json with a data measure.

Name	Type	Description
_did	string	device Id
_sid	string	sensor Id
data	string	return the real data that can be of type Boolean, integer, string or double. The casting is done using the sensorConfiguration by the driver automatically.
timestamp	date	date when the dataMeasure was taken by the sensor
status	string	ok/failure

Get Short-Term Historic Data from Device and Sensor

Endpoint to collect historic data from a sensor. The ID of the device and the ID of the sensor are provided in the request. The request can also provide cursors (ending_before, starting_after) to get a specific interval of the time series.

GET /api/drivers/v1/Devices/6G439Kl/Sensors/s5G439Kl/HistoricData?start=01/02/2017&end=12/02/2018 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "data":45.32,
    "unit":"degrees",
    "timestamp":"2017-06-07 18:00"
  },
  {
    "data":43.12,
    "unit":"degrees",
    "timestamp":"2017-06-07 18:05"
  },
  {
    "data":44.05,
    "unit":"degrees",
    "timestamp":"2017-06-07 18:10"
  }
]

Request

Request URL: GET /api/drivers/v1/Devices/<deviceId>/Sensors/<sensorId>/HistoricData?start=<startDate>date&end=<endDate>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	id of device
sensorId	Yes	Resource	string	id of sensor
startDate	Yes	Resource	date	date from which measures are returned
endDate	Yes	Resource	date	date until measures are returned

Response

Returns collection of measures Name | Type | Description ---- | ---- | --- _did| string| device Id _sid| string| sensor Id data| string| return the real data that can be of type Boolean, integer, string or double. The casting is done using the sensorConfiguration by the driver automatically. timestamp| date| date when the dataMeasure was taken by the sensor status| string| ok/failure

Send Command to Device / Sensor

Endpoint to send a command to a sensor of a device. The ID of the device and the ID of the sensor are provided in the request URL.

POST /api/drivers/v1/Devices/6G439Kl/Sensors/s5G439Kl/Command/ HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "commandtype":"type1",
  "command":"command X"
}

HTTP/1.1 200 OK

Request

Request URL: POST /api/drivers/v1/Devices/<deviceId>/Sensors/<sensorId>/Command/

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
deviceId	Yes	Resource	string	id of device
sensorId	Yes	Resource	string	id of sensor
commandOrder	Yes	Body	object	object with command sent to sensor
commandType	No	Body	string	for future usage where several type of command will be feasible
command	Yes	Body	string	value to be written in the sensor

Response

Returns 200 status code if the command was executed successfully. 400 code in case the command failed along with an error message

APIs

This specifies RESTful APIs of the API component. It provides a set of functionalities to manage the APIs and their lifecycle.

General URL

Requests are formatted with the following common variables.

Name	Example	Description
hostname	api-manager.vfos.com	Specifies the server host
port	9443	Specifies the server port
base_uri	/api	Specifies the base URI
version	1.0.0	API version
resource_uri	/apis	The uri of the resource

The URL is presented in the following format:
https://<hostname>:<port>/<base_uri>/<version>/<resource_uri>

The left part of the URL, up to the resource_uri, is common to all the API endpoints, so it will not be repeated in every interface in this documentation. The user should assume this should be prefixed to every endpoint:

List APIs

This operation provides a list of available APIs. Each retrieved API is represented with a minimal amount of attributes. If you want to get complete details of an API, you need to use Get details of an API operation.

GET /api/v0.11/apis?limit=25&offset=0 HTTP/1.1
Content-Type: application/json; charset=utf-8

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

{
  "count":2,
  "next":"",
  "previous":"",
  "list":[
    {
      "id":"747383bf-a531-4764-8a19-89b8646f754e",
      "name":"ccurentWeather",
      "description":null,
      "context":"/currentWeather/1",
      "version":"1",
      "provider":"admin",
      "status":"PUBLISHED"
    },
    {
      "id":"8cf7ea67-4e5a-4719-88ba-2ff80e2c6423",
      "name":"test2",
      "description":null,
      "context":"/test2/1.0.0",
      "version":"1.0.0",
      "provider":"admin",
      "status":"PUBLISHED"
    }
  ]
}

Request

Request URL : GET /apis?limit=<limit>&offset=<offset>

Request Parameters

Name	Required	Parameter Type	Object Type	Description
limit	Yes	Query	int	Maximum size of resource array to return
offset	Yes	Query	int	Starting point within the complete list of items qualified

Response

Returns Each retrieved API is represented with a minimal amount of attributes. If you want to get complete details of an API, you need to use Get details of an API operation.

Common status codes returned

Code	Description
200	List of qualifying APIs is returned
401	Unauthorized. The credentials provided are not valid
406	Not Acceptable. The requested media type is not supported

Get details of an API

This operation retrieves complete details of a single API. You need to provide the id of the API to retrieve.

GET /api/v0.11/apis/747383bf-a531-4764-8a19-89b8646f754e HTTP/1.1

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

{
  "id":"747383bf-a531-4764-8a19-89b8646f754e",
  "name":"ccurentWeather",
  "description":"Get current weather",
  "context":"/currentWeather/1",
  "version":"1",
  "provider":"admin",
  "apiDefinition":"{\"swagger\":\"2.0\",\"paths\":{\"/w\":{\"get\":{\"responses\":{\"200\":{\"description\":\"\"}},\"parameters\":[{\"name\":\"id\",\"in\":\"query\",\"required\":false,\"type\":\"string\"},{\"name\":\"APPID\",\"in\":\"query\",\"required\":false,\"type\":\"string\"}],\"x-auth-type\":\"Application & Application User\",\"x-throttling-tier\":\"Unlimited\"}}},\"info\":{\"title\":\"ccurentWeather\",\"version\":\"1\"}}",
  "wsdlUri":null,
  "status":"PUBLISHED",
  "isDefaultVersion":false,
  "transport":[
    "http"
  ],
  "tags":[
    "WEATHER"
  ],
  "tiers":[
    "Unlimited"
  ],
  "endpointURLs":[
    {
      "environmentURLs":{
        "https":null,
        "http":"http://159.84.110.177:8280/currentWeather/1"
      },
      "environmentName":"Production and Sandbox",
      "environmentType":"hybrid"
    }
  ]
}

Request

Request URL: GET /apis/<api_id>

Request Parameters

Name	Required	Parameter Type	Object Type	Description
api_id	Yes	Resource	string	UUID of the API

Response

Returns Successful response with the requested API in the body.

Name	Type	Description
id	string	UUID of the API
name	string	name of the API
description	string	Starting point within the complete list of items qualified
context	string	URI context path of the API
version	string	version of the API
provider	string	proider of the API
apiDefinition	string	Swagger definition of the API which contains details about URI templates and scopes.
wsdlUri	string	WSDL URL if the API is based on a WSDL endpoint
status	string	Statuts of the API
responseCaching	string	Enable/Disable the caching of token, version and name of API
cacheTimeout	integer	cache timeout
isDefaultVersion	boolean	Is this API the default version
type	string	type of the API
transport	string	Protocol to be used
tags	string	List of tags
tiers	string	Number of requests per minute
visibility	string	Visibility of the API
endpointConfig	string	Production endpoint of the API

Common status codes returned

Code	Description
200	The requested API in the body
404	Not Found. Requested API does not exist
406	Not Acceptable. The requested media type is not supported

Create API

This operation can be used by users who have permission to create APIs by specifying the details of the API in the payload.

POST /api/v0.11/apis HTTP/1.1
Content-Type: application/json

{
  "name":"ccurentWeather2",
  "description":null,
  "context":"/currentWeather2/all",
  "version":"1",
  "provider":"admin",
  "apiDefinition":"{\"swagger\":\"2.0\",\"paths\":{\"/w\":{\"get\":{\"responses\":{\"200\":{\"description\":\"\"}},\"parameters\":[{\"name\":\"id\",\"in\":\"query\",\"required\":false,\"type\":\"string\"},{\"name\":\"APPID\",\"in\":\"query\",\"required\":false,\"type\":\"string\"}],\"x-auth-type\":\"None\",\"x-throttling-tier\":\"Unlimited\"}}},\"info\":{\"title\":\"ccurentWeather2\",\"version\":\"1\"}}",
  "wsdlUri":null,
  "status":"PUBLISHED",
  "isDefaultVersion":false,
  "transport":[
    "http"
  ],
  "tags":[
    "WEATHER"
  ],
  "tiers":[
    "Unlimited"
  ],
  "endpointURLs":[
    {
      "environmentURLs":{
        "https":null,
        "http":"http://159.84.110.177:8280//currentWeather2/all"
      },
      "environmentName":"Production",
      "environmentType":"hybrid"
    }
  ]
}

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

{
  "id":"747383bf-a531-4764-8a19-89b8646f722e",
  "name":"ccurentWeather2",
  "description":null,
  "context":"/currentWeather2/all",
  "version":"1",
  "provider":"admin",
  "apiDefinition":"{\"swagger\":\"2.0\",\"paths\":{\"/w\":{\"get\":{\"responses\":{\"200\":{\"description\":\"\"}},\"parameters\":[{\"name\":\"id\",\"in\":\"query\",\"required\":false,\"type\":\"string\"},{\"name\":\"APPID\",\"in\":\"query\",\"required\":false,\"type\":\"string\"}],\"x-auth-type\":\"None\",\"x-throttling-tier\":\"Unlimited\"}}},\"info\":{\"title\":\"ccurentWeather2\",\"version\":\"1\"}}",
  "wsdlUri":null,
  "status":"PUBLISHED",
  "isDefaultVersion":false,
  "transport":[
    "http"
  ],
  "tags":[
    "WEATHER"
  ],
  "tiers":[
    "Unlimited"
  ],
  "endpointURLs":[
    {
      "environmentURLs":{
        "https":null,
        "http":"http://159.84.110.177:8280//currentWeather2/all"
      },
      "environmentName":"Production",
      "environmentType":"hybrid"
    }
  ]
}

Request

Request URL: POST /apis

Request Parameters

Name	Required	Parameter Type	Object Type	Description
name	Yes	Body	string	name of the API
description	No	Body	string	Starting point within the complete list of items qualified
context	Yes	Body	string	URI context path of the API
version	Yes	Body	string	version of the API
provider	No	Body	string	proider of the API
apiDefinition	Yes	Body	string	Swagger definition of the API which contains details about URI templates and scopes.
wsdlUri	No	Body	string	WSDL URL if the API is based on a WSDL endpoint
status	No	Body	string	Statuts of the API
responseCaching	No	Body	string	Enable/Disable the caching of token, version and name of API
cacheTimeout	No	Body	integer	cache timeout
isDefaultVersion	Yes	Body	boolean	Is this API the default version
type	Yes	Body	string	type of the API
transport	Yes	Body	string	Protocol to be used
tags	No	Body	string	List of tags
tiers	Yes	Body	string	Number of requests per minute
visibility	Yes	Body	string	Visibility of the API
endpointURLs	Yes	Body	string	Production endpoint of the API

Response

Returns Successful response with the newly created object as entity in the body. Location header contains URL of newly created entity..

Response header:

Header	Description
Content-Type	The content type of the body (application/json)
Location	The URL of the newly created resource

Common status codes returned

Code	Description
201	The newly created object as entity in the body
400	Bad Request. Invalid request or validation error.
415	Unsupported Media Type. The entity of the request was in a not supported format.

Update API Specifications

This operation can be used to update an existing API. But the properties name, version, context, provider, and status will not be changed by this operation.

PUT /api/v0.11/apis/747383bf-a531-4764-8a19-89b8646f754e HTTP/1.1
Content-Type: application/json

{
  "name":"curentWeather2",
  "description":"API New Description",
  "context":"/currentWeather2/all",
  "version":"1",
  "provider":"admin",
  "apiDefinition":"{\"swagger\":\"2.0\",\"paths\":{\"/w\":{\"get\":{\"responses\":{\"200\":{\"description\":\"\"}},\"parameters\":[{\"name\":\"id\",\"in\":\"query\",\"required\":false,\"type\":\"string\"},{\"name\":\"APPID\",\"in\":\"query\",\"required\":false,\"type\":\"string\"}],\"x-auth-type\":\"None\",\"x-throttling-tier\":\"Unlimited\"}}},\"info\":{\"title\":\"ccurentWeather2\",\"version\":\"1\"}}",
  "wsdlUri":null,
  "status":"PUBLISHED",
  "isDefaultVersion":true,
  "transport":[
    "http"
  ],
  "tags":[
    "WEATHER"
  ],
  "tiers":[
    "Unlimited"
  ],
  "endpointURLs":[
    {
      "environmentURLs":{
        "https":null,
        "http":"http://159.84.110.177:8280//currentWeather2/all"
      },
      "environmentName":"Production",
      "environmentType":"hybrid"
    }
  ]
}

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

{
  "id":"747383bf-a531-4764-8a19-89b8646f754e",
  "name":"curentWeather2",
  "description":"API New Description",
  "context":"/currentWeather2/all",
  "version":"1",
  "provider":"admin",
  "apiDefinition":"{\"swagger\":\"2.0\",\"paths\":{\"/w\":{\"get\":{\"responses\":{\"200\":{\"description\":\"\"}},\"parameters\":[{\"name\":\"id\",\"in\":\"query\",\"required\":false,\"type\":\"string\"},{\"name\":\"APPID\",\"in\":\"query\",\"required\":false,\"type\":\"string\"}],\"x-auth-type\":\"None\",\"x-throttling-tier\":\"Unlimited\"}}},\"info\":{\"title\":\"ccurentWeather2\",\"version\":\"1\"}}",
  "wsdlUri":null,
  "status":"PUBLISHED",
  "isDefaultVersion":true,
  "transport":[
    "http"
  ],
  "tags":[
    "WEATHER"
  ],
  "tiers":[
    "Unlimited"
  ],
  "endpointURLs":[
    {
      "environmentURLs":{
        "https":null,
        "http":"http://159.84.110.177:8280//currentWeather2/all"
      },
      "environmentName":"Production",
      "environmentType":"hybrid"
    }
  ]
}

Request

Request URL: PUT /apis/<api_id>

Request Parameters

Name	Required	Parameter Type	Object Type	Description
api_id	Yes	Resource	string	UUID of the API
name	Yes	Body	string	name of the API
description	No	Body	string	Starting point within the complete list of items qualified
context	Yes	Body	string	URI context path of the API
version	Yes	Body	string	version of the API
provider	No	Body	string	proider of the API
apiDefinition	Yes	Body	string	Swagger definition of the API which contains details about URI templates and scopes.
wsdlUri	No	Body	string	WSDL URL if the API is based on a WSDL endpoint
status	No	Body	string	Statuts of the API
responseCaching	No	Body	string	Enable/Disable the caching of token, version and name of API
cacheTimeout	No	Body	integer	cache timeout
isDefaultVersion	Yes	Body	boolean	Is this API the default version
type	Yes	Body	string	type of the API
transport	Yes	Body	string	Protocol to be used
tags	No	Body	string	List of tags
tiers	Yes	Body	string	Number of requests per minute
visibility	Yes	Body	string	Visibility of the API
endpointURLs	Yes	Body	string	Production endpoint of the API

Response

Returns Successful response with the updated API Object.

Common status codes returned

Code	Description
200	The updated API object as entity in the body
400	Bad Request. Invalid request or validation error
404	Not Found. The resource to be updated does not exist

Delete an API

This operation can be used to delete an existing API. You need to provide the id of the API to delete when sending the request.

DELETE /api/v0.11/apis/747383bf-a531-4764-8a19-89b8646f754e HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /apis/<api_id>

Request Parameters

Name	Required	Parameter Type	Object Type	Description
api_id	Yes	Resource	string	UUID of the API

Response

Returns OK. Resource successfully deleted.

Common status codes returned

Code	Description
200	Ok. Resource successfully deleted.
404	Not Found. Resource to be deleted does not exist.

Create new API version

This operation can be used to create a new version of an existing API. New API will be in CREATED state.

POST /api/v0.11/apis/<api_id>/versions?newVersion=<newVersion> HTTP/1.1

HTTP/1.1 201 Created
Content-Type: application/json
Location : /currentWeather/2

{
  "id":"465433bf-a522-4743-8a59-89b8646f754e",
  "name":"ccurentWeather",
  "description":null,
  "context":"/currentWeather/1",
  "version":"2.0.0",
  "provider":"admin",
  "apiDefinition":"{\"swagger\":\"2.0\",\"paths\":{\"/w\":{\"get\":{\"responses\":{\"200\":{\"description\":\"\"}},\"parameters\":[{\"name\":\"id\",\"in\":\"query\",\"required\":false,\"type\":\"string\"},{\"name\":\"APPID\",\"in\":\"query\",\"required\":false,\"type\":\"string\"}],\"x-auth-type\":\"Application & Application User\",\"x-throttling-tier\":\"Unlimited\"}}},\"info\":{\"title\":\"ccurentWeather\",\"version\":\"1\"}}",
  "wsdlUri":null,
  "status":"PUBLISHED",
  "isDefaultVersion":false,
  "transport":[
    "http"
  ],
  "tags":[
    "WEATHER"
  ],
  "tiers":[
    "Unlimited"
  ],
  "endpointURLs":[
    {
      "environmentURLs":{
        "https":null,
        "http":"http://159.84.110.177:8280//currentWeather/1"
      },
      "environmentName":"Production and Sandbox",
      "environmentType":"hybrid"
    }
  ]
}

Request

Request URL: POST /apis/<api_id>/versions?newVersion=<new_version>

Request Parameters

Name	Required	Parameter Type	Object Type	Description
api_id	Yes	Query	string	UUID of the API
new_version	Yes	Query	string	New version of the API

Response

Returns OK. Resource successfully created.

Common status codes returned

Code	Description
201	Created
400	Bad Request. Invalid request
404	Not Found. API to copy does not exist

Change API Lifecycle

This operation is used to change the lifecycle of an API.

Example: from CREATED status to Publish status. In order to change the lifecycle, we need to provide the lifecycle action as a query parameter.

POST /api/v0.11/apis/<api_id>/lifecycle HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "action":"Publish",
  "lifecycleChecklist":"Deprecate Old Versions"
}

HTTP/1.1 200 OK

Request

Request URL: POST /apis/<api_id>/lifecycle

Request Parameters

Name	Required	Parameter Type	Object Type	Description
api_id	Yes	Ressource	string	UUID of the API
action	Yes	Body	string	The action to demote or promote the state of the API. Supported actions are [ Publish, Deploy as a Prototype, Demote to Created, Demote to Prototyped, Block, Deprecate, Re-Publish, Retire ]
lifecycleChecklist	Yes	Body	string	to specify additional action when changing status of an API. Supported actions are : Deprecate Old Versions to deprecate old versions and Require Re-Subscription to force users to re subscribe to the API.

Response

Returns OK. Lifecycle changed successfully.

Common status codes returned

Code	Description
200	Ok. Lifecycle changed successfully.
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

ODBC API Connector

Open Database Connectivity (ODBC) API is a standard API to access database management systems. The purpose is to provide a unified API to access several database management systems. The ODBC API Connector can be therefore used by software applications to retrieve data from different database servers as MYSQL database, Oracle, DB2 and PostgreSQL.

The first API is getDbSchema This exposed service offers a REST endpoint to lists the non-temporary tables in a given database. If the user configured during the generation of the ODBC connector doesn’t have privileges for a base table or view, it does not show up in the output.

The second API is getRequestdb This function offers a REST endpoint that receives an SQL query to be executed in a given database. If the user configured during the generation of the ODBC Connector doesn’t have privileges for a table, view, or on a specific operation, the SQL request is not executed, and an error message is sent in the output to inform the user.

Request 1

Request URL:
http GET /api/v0.11/apis/odbc/v1/getDbSchema HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns Json file corresponding to the lists of the non-temporary tables in database.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 2

Request URL:
http GET /api/v0.11/apis/odbc/v1/getRequestdb HTTP/1.1 Content-Type: application/json; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
sqlRequest	Yes	Body	String	SQL Request to execute

Response

Returns Json file corresponding to the database response.

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

Excel File API Connector

The following Excel File Connector is a REST API that helps to import data through Excel files. The Excel File Connector parses spreadsheets in various Excel Workbook formats (eg XLS, XLSX) as well as other related formats (eg CSV) and serialize them in JSON format

The first API is readExcelFile. This service receives an Excel File (in xlsx, xls, or csv format), and serialize the content to JSON format which is sent back to the user. It offers also a serialization of the Excel file content for a specific tab in the Excel spreadsheet.

The second API is jsonToExcel. This service receives a Json file, and serialize the content to an Excel spreadsheet in xlsx format.

Request 1

Request URL:
http POST /api/v0.11/apis/excel/v1/readExcelFile HTTP/1.1 Content-Type: multipart/form-data; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
file	Yes	formData	File	Excel file to read
tabs	Yes	Body	int	tab sheet to read

Response

Returns Json file corresponding to the received Excel file.

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

Request 2

Request URL:
http POST /api/v0.11/apis/excel/v1/jsonToExcel HTTP/1.1 Content-Type: multipart/form-data; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
file	Yes	formData	File	Json file to convert

Response

Returns Excel spreadsheet in xlsx format.

Common status codes returned

Code	Description
200	Ok.
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

OData API Connector

The proposed OData API Connector helps to create and consume REST endpoints using OData Specification. When generating OData API Connector, an endpoint of the OData resource is required, with the entity name in order to consume the OData resources.

The first API is getODataEntity . This service offers a GET method to retrieve the collection of the configured entity.

The second API is getPreciseODataEntity. This service offers a GET method that filter a collection of resources that are addressed by a request.

Request 1

Request URL:
http GET /api/v0.11/apis/odata/v1/getODataEntity HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns Json file corresponding to the collection of the configured entity.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 2

Request URL:
http GET /api/v0.11/apis/odata/v1/getPreciseODataEntity HTTP/1.1 Content-Type: application/json; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
id	Yes	Body	String	Field 'name' in OData for a more precise request

Response

Returns Json file corresponding to the specific OData Object.

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

STEP File API Connector

Standard for the Exchange of Product Data (STEP) - STEP-NC AP238 Standard- is a file format used in CAD to work with 3D models. The STEP file format is widely used in the design of technical parts and is supported by the most popular CAD Software tools.

The STEP File Connector offers some functionalities to parse data from STEP files describing 3D models, allowing the use of this format in vApps for collaborative engineering.

The first API is parseStepFile . This service helps to extract information from the STEP file about the different features (parts of the 3D model) therein.

The second API is checkStepFile. This service helps to check if a given step file in a valid format and respect the specification for STEP-NC AP238 Standard

Request 1

Request URL:
http POST /api/v0.11/apis/step/v1/parseStepFile HTTP/1.1 Content-Type: multipart/form-data; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
file	Yes	formData	File	Step file to parse

Response

Returns Json file corresponding to the different features (parts of the 3D model) in the received STEP File.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 2

Request URL:
http GET /api/v0.11/apis/step/v1/checkStepFile HTTP/1.1 Content-Type: multipart/form-data; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
file	Yes	formData	File	Step file to verify

Response

HTTP/1.1 200 OK

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

External Service Provision

The External Service Provision (ESP) component provides a repository for wrapper and support libraries. The repository provides functionality to list all libraries inside the repository, to add libraries to it, and to delete obsolete libraries from the repository. From the perspective of the ESP repository itself, libraries are merely binary files with some metadata (name, type, version, author).

List libraries inside repository

Via this route a list of libraries can be retrieved from the ESP repository.

GET /esp/libraries HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id":"464576a076185ffb5c5eb9bc936f034a8b560773fecd23abe5ac54ba598b2b52",
    "name":"OpenWeatherMap Integration Library",
    "type":"jar",
    "version":"1.0.21",
    "author":"Ray Rutherford"
  },
  {
    "id":"299bdc0e4340d01081c2b2377f98b531bcda61151267b8351708df40563d1e8f",
    "name":"OpenERP Integration Library",
    "type":"js",
    "version":"3.14.05",
    "author":"OpenERP Community"
  }
]

Request

Request URL: GET /esp/libraries

Response

The list of libraries is returned in JSON format, with per library: id, name, type, version, and author.

Common Return Codes

Code	Description
200	OK
403	Forbidden
500	Internal Server Error

Get library from repository

Via this route, a library can be downloaded from the repository. The process takes place in two steps. In step 1, the metadata about the library is retrieved, including a Location URL. In step 2, the binary file may be received by using the Location URL.

GET /esp/libraries/464576a076185ffb5c5eb9bc936f034a8b560773fecd23abe5ac54ba598b2b52 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":"464576a076185ffb5c5eb9bc936f034a8b560773fecd23abe5ac54ba598b2b52",
  "name":"OpenWeatherMap Integration Library",
  "type":"jar",
  "version":"1.0.21",
  "author":"Ray Rutherford",
  "location":"/esp/blobs/7e3f4d4e7f6c606d2d3109b296a2894301f76d9d002d4394/owm1-0-21.jar"
}

Request

Request URL: GET /esp/libraries/<library_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
library_id	Yes	Resource	String	Identifier for a library to be requested

Response

The response provides the metadata about the library, including a Location URL for downloading the library binary file.

Common Return Codes

Code	Description
200	OK
403	Forbidden
404	Not found
500	Internal Server Error

Add library to repository

Via this route a library can be added to the ESP repository. Adding an item to the ESP repository use two steps. The first step uploads the metadata and returns a Location URL to carry out the second step. The second step uses the Location URL to transfer the library binary file via a POST request.

POST /esp/libraries HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "id":"464576a076185ffb5c5eb9bc936f034a8b560773fecd23abe5ac54ba598b2b52",
  "name":"OpenWeatherMap Integration Library",
  "type":"jar",
  "version":"1.0.21",
  "author":"Ray Rutherford",
  "filename":"owm1-0-21.jar",
  "digest":"e8a65a856cd552c280034843622ddce0a8b83f567469eb2264389690d0851be5"
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "id":"464576a076185ffb5c5eb9bc936f034a8b560773fecd23abe5ac54ba598b2b52",
  "location":"/esp/blobs/7e3f4d4e7f6c606d2d3109b296a2894301f76d9d002d4394"
}

POST /esp/blobs/7e3f4d4e7f6c606d2d3109b296a2894301f76d9d002d4394 HTTP/1.1
Content-Type: octet-stream

HTTP/1.1 201 Created

First Request

First Request URL: POST /esp/libraries

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
Library Object	yes	Body entity	JSON object	The library object consists of the following attributes name: Description of the library type: Type of (binary or text) file version: Version number for the library author: Identifier for the author(s) of the library filename: name of the binary file to be uploaded later digest: SHA256 hash for the binary file to be uploaded later

First Response

The client will receive a 201 Created response returning a JSON structure with a new id for the created entity and a location to POST the binary.

Common Return Codes (First Step)

These are the codes returned in the first step:

Code	Description
201	Created
400	Malformed Request
403	Forbidden
500	Internal Server Error

Second Request

Second Request URL: POST <location>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
location	Yes	Endpoint	String	Identifier for the endpoint where the library can be posted

Second Response

The client can now POST the binary file. The file will get the name provided earlier. If the digest provided earlier matches with the SHA256 hash for the binary, this request will complete with a HTTP/1.1 201 Created and the process can be considered complete.

Common Return Codes (Second Step)

These are the codes returned in the second step:

Code	Description
201	Created
403	Forbidden
409	Conflict (with digest provided earlier)
500	Internal Server Error

Delete library from repository

Via this route a library can be deleted from the repository.

DELETE /esp/libraries/464576a076185ffb5c5eb9bc936f034a8b560773fecd23abe5ac54ba598b2b52 HTTP/1.1

HTTP/1.1 200 OK

Request

Request URL: DELETE /esp/libraries/<library_id>

Transfer Parameter

Name	Required	Parameter Type	Object Type	Description
library_id	Yes	Resource	String	Identifier for a specific library

Response

If successful, the response will be 200 OK. Otherwise, an error is returned.

Common Return Codes

Code	Description
200	OK
403	Forbidden
404	Not found
500	Internal Server Error

Control

Security - Basics

The vf-OS security provides capabilities for controlling and authorizing the access to assets and other components of the system.

Security - Identity Management

This section covers the main functionalities of the identity service:

• Authentication and token management
• Users
• Groups
• Roles
• Policies

Authentication and token management

This API describes the main operations with regard to authentication and token management In exchange for a set of authentication credentials, the Identity service generates tokens. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project or domain.

The body of an authentication request must include a payload that specifies the authentication method, which is password or token, the credentials, and, optionally, the authorization scope.

Tokens have IDs, which the Identity API returns in the X-Subject-Token response header.

Also, validates an authentication token and lists the domains, projects, roles, and endpoints to which the token gives access. Forces the immediate revocation of a token.

After you obtain an authentication token, you can:

• Make REST API requests to other vf-OS services. You supply the ID of your authentication token in the X-Auth-Token request header.
• Validate your authentication token and list the domains, projects, roles, and endpoints that your token gives you access to.
• Use your token to request another token scoped for a different domain and project.
• Force the immediate revocation of a token.
• List revoked public key infrastructure (PKI) tokens.

Common status codes returned

Code	Description
400	Bad Request. The Identity service failed to parse the request as expected. One of the following errors occurred: a required attribute was missing, an attribute that is not allowed was specified, such as an ID on a POST request in a basic CRUD operation, or an attribute of an unexpected data type was specified.
401	Unauthorized. One of the following errors occurred: authentication was not performed, the specified X-Auth-Token header is not valid, or the authentication credentials are not valid.
403	Forbidden. The identity was successfully authenticated but it is not authorized to perform the requested action.
404	Not Found. An operation failed because a referenced entity cannot be found by ID. For a POST request, the referenced entity might be specified in the request body rather than in the resource path.
409	Conflict. A POST or PATCH operation failed. For example, a client tried to update a unique attribute for an entity, which conflicts with that of another entity in the same collection. Or, a client issued a create operation twice on a collection with a user-defined, unique attribute. For example, a client made a POST /users request two times for the unique, user-defined name attribute for a user entity.

Check Token

Checks the validity of a token

HEAD /v1/auth/tokens HTTP/1.1
X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
X-Subject-Token: gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99B
allow-expired: True

HTTP/1.1 200 OK

Request

Request URL: HEAD /auth/tokens

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
X-Auth-Token	Yes	Header	String	A valid authentication token for an administrative user.
X-Subject-Token	Yes	Header	String	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
allow_expired (Optional)	Yes	query	bool	Allow fetching a token that has expired. By default expired tokens return a 404 exception.

Validate and show information for token

Validates and shows information for a token, including its expiration date and authorization scope.

GET /v1/auth/tokens HTTP/1.1
X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
X-Subject-Token: gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99B
allow-expired: True

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token":{
    "methods":[
      "token"
    ],
    "expires_at":"2015-11-05T22:00:11.000000Z",
    "user":{
      "domain":{
        "id":"default",
        "name":"Default"
      },
      "id":"10a2e6e717a245d9acad3e5f97aeca3d",
      "name":"admin",
      "password_expires_at":null
    },
    "issued_at":"2015-11-05T21:00:33.819948Z"
  }
}

Request

Request URL: GET /auth/tokens

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
X-Auth-Token	Yes	Header	String	A valid authentication token for an administrative user.
X-Subject-Token	Yes	Header	String	The authentication token. An authentication response returns the token ID in this header rather than in the response body.
allow_expired (Optional)	Yes	query	bool	Allow fetching a token that has expired. By default expired tokens return a 404 exception.

Revoke token

Revokes a token.

GET /v1/auth/tokens HTTP/1.1
X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
X-Subject-Token: gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99B

HTTP/1.1 204 OK

Request

Request URL: DELETE /auth/tokens

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
X-Auth-Token	Yes	Header	String	A valid authentication token for an administrative user.
X-Subject-Token	Yes	Header	String	The authentication token. An authentication response returns the token ID in this header rather than in the response body.

Password authentication

Authenticates an identity and generates a token. Uses the password authentication method and scopes authorization to a project or domain.

POST /v1/auth/tokens HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "auth":{
    "identity":{
      "methods":[
        "password"
      ],
      "password":{
        "user":{
          "id":"ee4dfb6e5540447cb3741905149d9b6e",
          "password":"devstacker"
        }
      }
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "token":{
    "methods":[
      "password"
    ],
    "user":{
      "domain":{
        "id":"default",
        "name":"Default"
      },
      "id":"ee4dfb6e5540447cb3741905149d9b6e",
      "name":"admin",
      "password_expires_at":"2016-11-06T15:32:17.000000"
    },
    "issued_at":"2015-11-07T01:58:43.578929Z"
  }
}

Request

Request URL: POST /auth/tokens

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
auth	Yes	Body	Object	An auth object.
user	Yes	Body	Object	A user object.
password	Yes	Body	Object	The password object, contains the authentication information.
identity	Yes	Body	Object	An identity object.
method	Yes	Body	Array	The authentication method. For password authentication, specify password.

Token authentication

Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project or domain.

POST /v1/auth/tokens HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "auth":{
    "identity":{
      "methods":[
        "token"
      ],
      "token":{
        "id":"'$OS_TOKEN'"
      }
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "token":{
    "methods":[
      "token"
    ],
    "roles":[
      {
        "id":"5090055d6bd547dc83e0e8f070803708",
        "name":"admin"
      }
    ],
    "expires_at":"2015-11-05T22:00:11.000000Z",
    "project":{
      "domain":{
        "id":"default",
        "name":"Default"
      },
      "id":"5b50efd009b540559104ee3c03bbb2b7",
      "name":"admin"
    },
    "is_domain":false,
    "catalog":[
      {
        "endpoints":[
          {
            "region_id":"RegionOne",
            "url":"http://23.253.248.171:9292",
            "region":"RegionOne",
            "interface":"admin",
            "id":"b2605da9b25943beb49b2bd86aca2202"
          },
          {
            "region_id":"RegionOne",
            "url":"http://23.253.248.171:9292",
            "region":"RegionOne",
            "interface":"public",
            "id":"c4d1184caf8c4351bff4bf502a09684e"
          },
          {
            "region_id":"RegionOne",
            "url":"http://23.253.248.171:9292",
            "region":"RegionOne",
            "interface":"internal",
            "id":"cd73bda89e3948738c2721a8c3acac54"
          }
        ],
        "type":"image",
        "id":"495df2483dc145dbb6b34bfbdd787aae",
        "name":"glance"
      },
      {
        "endpoints":[
          {
            "region_id":"RegionOne",
            "url":"http://23.253.248.171:8773/",
            "region":"RegionOne",
            "interface":"internal",
            "id":"7d03218a7f4246e8b9e3992318bf5397"
          },
          {
            "region_id":"RegionOne",
            "url":"http://23.253.248.171:8773/",
            "region":"RegionOne",
            "interface":"public",
            "id":"9ad7f8ce438c4212b8aac930bca04c86"
          },
          {
            "region_id":"RegionOne",
            "url":"http://23.253.248.171:8773/",
            "region":"RegionOne",
            "interface":"admin",
            "id":"d84aad1a45c44e4da09b719167383049"
          }
        ],
        "type":"ec2",
        "id":"54204024bb7d4665a8efc34fc758f1f7",
        "name":"ec2"
      }
    ],
    "user":{
      "domain":{
        "id":"default",
        "name":"Default"
      },
      "id":"10a2e6e717a245d9acad3e5f97aeca3d",
      "name":"admin",
      "password_expires_at":"2016-11-06T15:32:17.000000"
    },
    "issued_at":"2015-11-05T21:32:30.505384Z"
  }
}

Request

Request URL: POST /auth/tokens

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
methods	Yes	Body	Array	The authentication method. For token authentication, specify token.
auth	Yes	Body	Object	An auth object.
token	Yes	Body	Object	A token object. The token authentication method is used. This method is typically used in combination with a request to change authorization scope.
audit_ids	Yes	Body	Array	A list of one or two audit IDs.
id	Yes	Body	string	A token ID.
identity	Yes	Body	Object	An identity object.

Users

A user is an individual API consumer that is owned by a domain. A role explicitly associates a user with projects or domains. A user with no assigned roles has no access to vf-OS resources. You can list, create, show details for, update, delete, and change the password for users. You can also list groups, projects, and role assignments for a specified user. To list user roles, see Roles.

List Users

Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project or domain.

GET /users HTTP/1.1

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8

{
  "users":[
    {
      "domain_id":"default",
      "enabled":true,
      "id":"2844b2a08be147a08ef58317d6471f1f",
      "links":{
        "self":"http://example.com/identity/v3/users/2844b2a08be147a08ef58317d6471f1f"
      },
      "name":"glance",
      "password_expires_at":null
    },
    {
      "domain_id":"default",
      "enabled":true,
      "id":"4ab84ab39de54f4d96eaff8f2145a7cd",
      "links":{
        "self":"http://example.com/identity/v3/users/4ab84ab39de54f4d96eaff8f2145a7cd"
      },
      "name":"swiftusertest1",
      "password_expires_at":"2016-11-06T15:32:17.000000"
    }
  ]
}

Request URL: GET /users

Common status codes returned

Code	Description
200	OK
400	Bad request
401	Not authorized
403	Forbidden

Create User

A user is an individual API consumer that is owned by a domain. A role explicitly associates a user with projects or domains. A user with no assigned roles has no access to vf-OS resources.

POST /users HTTP/1.1

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "user":{
    "default_project_id":"263fd9",
    "domain_id":"1789d1",
    "enabled":true,
    "name":"James Doe",
    "password":"secretsecret"
  }
}

Request URL: POST /users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user	Yes	Body	Object	A user object
name	Yes	Body	String	The user name. Must be unique within the owning domain.
password	Yes	Body	String	The password for the user.

Common status codes returned

Code	Description
201	Created.
400	Bad request.
401	Not authorized.
403	Forbidden.
409	Conflict.

Show user details

Shows details for a user.

GET /users/vfos_user1 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user":{
    "enabled":true,
    "id":"9fe1d3",
    "name":"jsmith",
    "password_expires_at":"2016-11-06T15:32:17.000000"
  }
}

Request URL: GET /users/<user_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user	Yes	Body	Object	A user object
name	Yes	Body	String	The user name. Must be unique within the owning domain.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Update User

Updates a user’s password, or whether they are enabled or disabled.

PATCH /users/vfos_user1 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "user":"john_smith",
  "password":"mypassword"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user":{
    "enabled":true,
    "id":"ff4e51",
    "name":"jamesdoe",
    "password_expires_at":"2016-11-06T15:32:17.000000"
  }
}

Request URL: PATCH /users/<user_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	The user ID
user	Yes	Body	Object	A user object
password	Yes	Body	String	The password for the user.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.
409	Conflict.

Delete User

Deletes a user.

DELETE /users/vfos_user1 HTTP/1.1

HTTP/1.1 204 OK

Request URL: DELETE /users/<user_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	The user ID

Common status codes returned

Code	Description
204	No content.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

List groups to which a user belongs

Lists groups to which a user belongs.

PATCH /users/vfos_user1/groups HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "groups":[
    {
      "description":"Developers cleared for work on all general projects",
      "id":"ea167b",
      "name":"Developers"
    },
    {
      "description":"Developers cleared for work on secret projects",
      "id":"a62db1",
      "name":"Secure Developers"
    }
  ]
}

Request URL: GET /users/<user_id>/groups

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	The user ID

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Change password

Changes the password for a user.

POST /users/vfos_user1/password HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "user":{
    "password":"new_secretsecret",
    "original_password":"secretsecret"
  }
}

HTTP/1.1 204 OK

Request URL: POST /users/<user_id>/password

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	The user ID
user	Yes	Body	Object	A user object
original_password	Yes	Body	String	The password for the user.
password	Yes	Body	String	The password for the user.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Groups

A group is a collection of users. Each group is owned by a domain. You can use groups to ease the task of managing role assignments for users. Assigning a role to a group on a project or domain is equivalent to assigning the role to each group member on that project or domain. When you unassign a role from a group, that role is automatically unassigned from any user that is a member of the group. Any tokens that authenticates those users to the relevant project or domain are revoked.

As with users, a group without any role assignments is useless from the perspective of an vf-OS service and has no access to resources. However, a group without role assignments is permitted as a way of acquiring or loading users and groups from external sources before mapping them to projects and domains.

List groups

Lists groups to which a user belongs.

GET /groups HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "groups":[
    {
      "description":"non-admin group",
      "id":"96372bbb152f475aa37e9a76a25a029c",
      "name":"nonadmins"
    },
    {
      "description":"vf-os admin group",
      "id":"9ce0ad4e58a84d7a97b92f7955d10c92",
      "name":"admins"
    }
  ]
}

Request URL: GET /groups

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
name	No	Query	String	The user ID
domain_id	No	Query	String	The user ID

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.

Create Group

A user is an individual API consumer that is owned by a domain. A role explicitly associates a user with projects or domains. A user with no assigned roles has no access to vf-OS resources.

POST /groups HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "group":{
    "description":"Contract developers",
    "domain_id":"default",
    "name":"Contract developers"
  }
}

HTTP/1.1 201 Created

Request URL: POST /groups

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
group	Yes	Body	Object	A group object
name	Yes	Body	String	The name of the group

Common status codes returned

Code	Description
201	Created.
400	Bad request.
401	Not authorized.
403	Forbidden.
409	Conflict.

Update Group

Updates a group.

Request

Request URL: PATCH /groups/<group_id>

PATCH /groups/grp1102 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "group":{
    "description":"Contract developers 2016",
    "name":"Contract developers 2016"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "group":{
    "description":"Contract developers 2016",
    "id":"c0d675eac29945ad9dfd08aa1bb75751",
    "name":"Contract developers 2016"
  }
}

Name	Required	Parameter Type	Object Type	Description
group_id	Yes	Path	String	A group ID
group	Yes	Body	Object	A group object

Response

Name	Required	Type	Description
group	body	object	A group object, containing:
description	body	string	The description of the group.
domain_id	body	string	The ID of the domain of the group.
id	body	string	The ID of the group.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.
409	Conflict.

Delete Group

Deletes a group.

DELETE /groups/grp1102 HTTP/1.1

HTTP/1.1 204 OK

Request URL: DELETE /groups/<group_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
group_id	Yes	Path	String	A group ID

Common status codes returned

Code	Description
204	No content.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

List users in group

Deletes a group.

GET /groups/grp1102/users HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "users":[
    {
      "description":null,
      "enabled":true,
      "id":"acd565a08293c1e48bc0dd0d72ad5d5d",
      "name":"Henry"
    },
    {
      "description":null,
      "enabled":true,
      "id":"fff603a0829d41e48bc0dd0d72ad61ce",
      "name":"Paul",
      "password_expires_at":"2016-11-06T15:32:17.000000"
    }
  ]
}

Request URL: GET /groups/<group_id>/users

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
group_id	Yes	Path	String	A group ID

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Add users to group

Adds a user to a group. http PUT /groups/grp1102/users/vfos_user1 HTTP/1.1

HTTP/1.1 200 OK

Request URL: PUT /groups/<group_id>/users/<user_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	A user ID
group_id	Yes	Path	String	A group ID

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Remove a user from group

Removes a user from a group.

DELETE /groups/grp1102/users/vfos_user1 HTTP/1.1

HTTP/1.1 200 OK

Request URL: DELETE /groups/<group_id>/users/<user_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	A user ID
group_id	Yes	Path	String	A group ID

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Check whether user belongs to group

Validates that a user belongs to a group.

HEAD /groups/grp1102/users/vfos_user1 HTTP/1.1

HTTP/1.1 204 OK

Request URL: HEAD /groups/<group_id>/users/<user_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Path	String	A user ID
group_id	Yes	Path	String	A group ID

Common status codes returned

Code	Description
204	No content.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Roles

vf-OS services typically determine whether a user’s API request should be allowed using Role Based Access Control (RBAC). For vf-OS this means the service compares the roles that user has on the project (as indicated by the roles in the token), against the roles required for the API in question (as defined in the service’s policy file). A user obtains roles on a project by having these assigned to them via the Identity service API.

Roles must initially be created as entities via the Identity services API and, once created, can then be assigned. You can assign roles to a user or group on a project, including projects owned by other domains. You can also assign roles to a user or group on a domain, although this is only currently relevant for using a domain scoped token to execute domain-level Identity service API requests.

The creation, checking and deletion of role assignments is done with each of the attributes being specified in the URL

List roles

Lists roles.

GET /roles HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "roles":[
    {
      "id":"5318e65d75574c17bf5339d3df33a5a3",
      "name":"admin"
    },
    {
      "id":"642bcfc75c384fd181adf34d9b2df897",
      "name":"anotherrole"
    },
    {
      "id":"779a76d74f544224a7ef8762ca0de627",
      "name":"Member"
    },
    {
      "id":"9fe2ff9ee4384b1894a90878d3e92bab",
      "name":"_member_"
    },
    {
      "id":"ba2dfba61c934ee89e3110de36273229",
      "name":"ResellerAdmin"
    },
    {
      "id":"f127b97616f24d3ebceb7be840210adc",
      "name":"service"
    }
  ]
}

Request URL: GET /roles

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
name	No	query	String	Filters the response by a role name.
domain_id	No	query	String	Filters the response by a domain ID.

Response

Name	Required	Type	Description
roles	body	array	A list of role objects, each containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.

Create role

Creates a role.

POST /roles HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "role":{
    "name":"developer"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "role":{
    "domain_id":"92e782c4988642d783a95f4a87c3fdd7",
    "name":"developer"
  }
}

Request URL: POST /roles

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
role	Yes	body	object	A role object, containing:
name	Yes	body	String	The role name.
domain_id	Yes	body	String	The ID of the domain of the role.

Response

Name	Required	Type	Description
role	body	object	A role object, containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Common status codes returned

Code	Description
201	Created.
400	Bad request.
401	Not authorized.
403	Forbidden.
409	Conflict.

Update role

Updates a role.

PATCH /roles/rol_admin HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "role":{
    "name":"developer"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "role":{
    "id":"1e443fa8cee3482a8a2b6954dd5c8f12",
    "name":"developer"
  }
}

Request URL: PATCH /roles/<role_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
role_id	Yes	path	string	The role ID.
role	Yes	body	object	A role object, containing:
name	No	body	String	The role name.

Response

Name	Required	Type	Description
role	body	object	A role object, containing:
domain_id	body	string	The ID of the domain.
id	body	string	The role ID.
links	body	object	The link to the resources in question.
name	body	string	The role name.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
409	Conflict.

Delete role

Deletes a role.

DELETE /roles/rol_admin HTTP/1.1

HTTP/1.1 200 OK

Request URL: DELETE /roles/<role_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
role_id	Yes	path	string	The role ID.

Common status codes returned

Code	Description
204	No content.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Assign role to a group

Assigns a role to a group

PUT /domains/vfos/groups/developers/roles/devel HTTP/1.1

HTTP/1.1 200 OK

Request URL: PUT /domains/<domain_id>/groups/<group_id>/roles/<role_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
domain_id	Yes	path	string	The ID of the domain.
group_id	Yes	path	string	The ID of the group.
role_id	Yes	path	string	The role ID.

Common status codes returned

Code	Description
204	No content.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.
409	Conflict.

Unassign role to a group

Unassigns a role to a group

DELETE /domains/vfos/groups/developers/roles/devel HTTP/1.1

HTTP/1.1 204 OK

Request URL: DELETE /domains/<domain_id>/groups/<group_id>/roles/<role_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
domain_id	Yes	path	string	The ID of the domain.
group_id	Yes	path	string	The ID of the group.
role_id	Yes	path	string	The role ID.

Common status codes returned

Code	Description
204	No content.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Policies

A policy is an arbitrarily serialized policy engine rule set to be consumed by a remote service.

Create policy

Creates a policy.

POST /policies HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "policy":{
    "blob":"{'foobar_user': 'role:compute-user'}",
    "type":"application/json"
  }
}

HTTP/1.1 201 OK

Request URL: POST /policies

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
policy	Yes	body	object	A policy object.
type	Yes	body	string	The MIME media type of the serialized policy blob.
blob	Yes	body	string	The policy rule set itself, as a serialized blob.

Common status codes returned

Code	Description
201	Created.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Update policy

Updates a policy

PATCH /policies/pol112 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "policy":{
    "blob":{
      "foobar_user":[
        "role:compute-user"
      ]
    },
    "type":"application/json"
  }
}

HTTP/1.1 200 OK

Request URL: PATCH /policies/<policy_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
policy_id	Yes	path	string	A policy ID.
policy	Yes	body	object	A policy object.
type	Yes	body	string	The MIME media type of the serialized policy blob.
blob	Yes	body	object	The policy rule set itself, as a serialized blob.

Common status codes returned

Code	Description
201	Created. Resource was created and is ready to use.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Show policy details

Shows details for a policy.

GET /policies/pol112 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "policy":{
    "blob":{
      "foobar_user":[
        "role:compute-user"
      ]
    },
    "id":"717273",
    "type":"application/json"
  }
}

Request URL: GET /policies/<policy_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
policy_id	Yes	path	string	A policy ID.

Response

Name	Required	Type	Description
links	body	object	The links for the policy resource.
blob	body	string	The policy rule itself, as a serialized blob.
policy	body	string	A policy object.
type	string	object	The MIME media type of the serialized policy blob.
id	string	string	The policy ID.

Common status codes returned

Code	Description
200	OK. Request was successful.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

List policies

Shows details for a policy.

GET /policies/pol112 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "policies":[
    {
      "blob":{
        "foobar_user":[
          "role:compute-user"
        ]
      },
      "id":"717273",
      "type":"application/json"
    },
    {
      "blob":{
        "foobar_user":[
          "role:compute-user"
        ]
      },
      "id":"717274",
      "type":"application/json"
    }
  ]
}

Request URL: GET /policies/<policy_id>

Response

Name	Required	Type	Description
links	body	object	The links for the policy resource.
blob	body	string	The policy rule itself, as a serialized blob.
policy	body	string	A policy object.
type	string	object	The MIME media type of the serialized policy blob.
id	string	string	The policy ID.

Common status codes returned

Code	Description
200	OK.
400	Bad request.
401	Not authorized.
403	Forbidden.
404	Not found.

Security - Policy Decision Point

This section covers the main functionalities of the identity service

Policy Administration API

The Policy Administration API (PAP) is used by policy administrators to manage the policy repository from which the PDP loads the enforced policies. The PAP supports multi-tenancy in the form of generic administration domains that are separate from each other.

Each policy administrator (except the Superadmin) is in fact a domain administrator, insofar as he is allowed to manage the policy for one or more specific domains. Domains are typically used to support isolation of tenants (one domain per tenant).

Add policy

Add policy

POST /domains/factory1/pap/policies HTTP/1.1
Content-Type: application/xml

<Policy PolicyId="SamplePolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides">
  <!-- This Policy only applies to requests on the SampleServer -->
  <Target>
    <Subjects>
      <AnySubject />
    </Subjects>
    <Resources>
      <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">SampleServer</AttributeValue>
        <ResourceAttributeDesignator DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" />
      </ResourceMatch>
    </Resources>
    <Actions>
      <AnyAction />
    </Actions>
  </Target>
  <!-- Rule to see if we should allow the Subject to login -->
  <Rule RuleId="LoginRule" Effect="Permit">
    <!-- Only use this Rule if the action is login -->
    <Target>
      <Subjects>
        <AnySubject />
      </Subjects>
      <Resources>
        <AnyResource />
      </Resources>
      <Actions>
        <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
          <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">login</AttributeValue>
          <ActionAttributeDesignator DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="ServerAction" />
        </ActionMatch>
      </Actions>
    </Target>
    <!-- Only allow logins from 9am to 5pm -->
    <Condition FunctionId="urn:oasis:names:tc:xacml:1.0:function:and">
      <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-greater-than-or-equal">
        <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-one-and-only">
          <EnvironmentAttributeSelector DataType="http://www.w3.org/2001/XMLSchema#time" AttributeId="urn:oasis:names:tc:xacml:1.0:environment:current-time" />
        </Apply>
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#time">09:00:00</AttributeValue>
      </Apply>
      <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-less-than-or-equal">
        <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-one-and-only">
          <EnvironmentAttributeSelector DataType="http://www.w3.org/2001/XMLSchema#time" AttributeId="urn:oasis:names:tc:xacml:1.0:environment:current-time" />
        </Apply>
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#time">17:00:00</AttributeValue>
      </Apply>
    </Condition>
  </Rule>
  <!-- We could include other Rules for different actions here -->
  <!-- A final, "fall-through" Rule that always Denies -->
  <Rule RuleId="FinalRule" Effect="Deny" />
</Policy>

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

<PolicySet xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicySetId="P1" Version="1.0" ... />

Request URL: POST /domains/<domainId>/pap/policies

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
Poicy	Yes	Body	String	XACML PolicySet as defined in the XACML 3.0 schema.

Getting Policies and Policy Versions

Generates policies and policy versions

GET /domains/factory1/pap/policies HTTP/1.1
Content-Type: application/xml

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

<Policy PolicyId="SamplePolicy" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides">
  <!-- This Policy only applies to requests on the SampleServer -->
  <Target>
    <Subjects>
      <AnySubject />
    </Subjects>
    <Resources>
      <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">SampleServer</AttributeValue>
        <ResourceAttributeDesignator DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" />
      </ResourceMatch>
    </Resources>
    <Actions>
      <AnyAction />
    </Actions>
  </Target>
  <!-- Rule to see if we should allow the Subject to login -->
  <Rule RuleId="LoginRule" Effect="Permit">
    <!-- Only use this Rule if the action is login -->
    <Target>
      <Subjects>
        <AnySubject />
      </Subjects>
      <Resources>
        <AnyResource />
      </Resources>
      <Actions>
        <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
          <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">login</AttributeValue>
          <ActionAttributeDesignator DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="ServerAction" />
        </ActionMatch>
      </Actions>
    </Target>
    <!-- Only allow logins from 9am to 5pm -->
    <Condition FunctionId="urn:oasis:names:tc:xacml:1.0:function:and">
      <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-greater-than-or-equal">
        <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-one-and-only">
          <EnvironmentAttributeSelector DataType="http://www.w3.org/2001/XMLSchema#time" AttributeId="urn:oasis:names:tc:xacml:1.0:environment:current-time" />
        </Apply>
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#time">09:00:00</AttributeValue>
      </Apply>
      <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-less-than-or-equal">
        <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:time-one-and-only">
          <EnvironmentAttributeSelector DataType="http://www.w3.org/2001/XMLSchema#time" AttributeId="urn:oasis:names:tc:xacml:1.0:environment:current-time" />
        </Apply>
        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#time">17:00:00</AttributeValue>
      </Apply>
    </Condition>
  </Rule>
  <!-- We could include other Rules for different actions here -->
  <!-- A final, "fall-through" Rule that always Denies -->
  <Rule RuleId="FinalRule" Effect="Deny" />
</Policy>

Request URL: GET /domains/<domainId>/pap/policies/<policyId>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
Domain_id	Yes	Path	String	Domain ID.
Policy_id	Yes	Path	String	Poilcy ID.

Removing Policies and Policy Versions

Removes policies and policy versions

DELETE /domains/factory11/pap/policies/pol11/<version> HTTP/1.1

HTTP/1.1 200 OK

Request URL: DELETE /domains/<domainId>/pap/policies/<policyId>/<version>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
Domain_id	Yes	Path	String	Domain ID.
Policy_id	Yes	Path	String	Poilcy ID.

Policy decision API

The PDP API returns an authorization decision based on the currently enforced policy, access control attributes provided in the request and possibly other attributes resolved by the PDP itself. The Authorization decision is typically Permit or Deny. The PDP is able to resolve extra attributes not provided directly in the request, such as the current date/time (environment attribute).

POST /domains/factory11/pdp HTTP/1.1
Content-Type: application/xml

<Request xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" ... />

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

<Response xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" ... />

Request URL: POST /domains/<domainId>/pdp

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
Domain_id	Yes	Path	String	Domain ID.

System Dashboard

The System Dashboard component presents an overview of dashboards to the end user for all components and vApps. For this, a technical approach will be applied which is exactly the same as the approach taken for the Platform Portal Services: the components and vApps may provide a simple HTTP server for their dashboard (for more documentation, see Platform Portal Services). Each component is required to serve its dashboard in two ways: as an icon (for the overview page) and as an application running inside a smaller window (ie not fullscreen).

By definition, the System Dashboard also presents the dashboard for the Platform Execution Services. However, for this component, an exception has been made: the System Dashboard will use the public REST API provided by the Platform Execution Services and it will itself perform the HTML rendering for this dashboard.

Marketplace Services

Marketplace

The vf-OS Marketplace offers fundamental services of a modern e-Commerce platform for consumer and developers. First, vf-Store enables software developers to offer assets (demanded or initiative), and second, users are able to search for, obtain and rate existing vApps. Furthermore, the vf-Store acts as a mediator between developers and users. Therefore, the vf-Store is the central point for developers to get in contact with users. In addition to view/set ratings, reviews, and technical information about the asset's behaviour, the vf-Store supports users to get in contact with developers to offer ideas for new assets.

Send payment notifications

Via this route payment providers can send updates for payments related to orders.

POST https://vfos-datahub.ascora.de/v1/paymentnotifications HTTP/1.1

HTTP/1.1 201 Created

Request

The request contains multiple fields – required and non-required ones.

Request URL: POST /v1/paymentnotifications

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
accessid	Yes	Body	string	Access ID
aid	Yes	Body	int	Sub Account ID
balance	Yes	Body	float	Balance of the customer at the payment provider
clearingtype	Yes	Body	string	Used payment method
customerid	Yes	Body	int	Customer ID in the user's system
failedcause	No	Body	string	Reason why the payment failed
key	Yes	Body	string	Key to authenticate notification
mode	Yes	Body	string	live or test
portalid	Yes	Body	int	Portal ID
param	No	Body	string	Additional information
receivable	Yes	Body	float	Total payment request (in largest currency unit eg Euro)
reference	Yes	Body	string	Order ID at the user's system
reminderlevel	No	Body	string	Customer's reminder status
time	Yes	Body	int	Timestamp of notification
txaction	Yes	Body	string	Reason for notification
txid	Yes	Body	int	Notification ID
userid	Yes	Body	int	ID of the customer at the payment provider

Response

The response does not contain any content in the success case. The API answers with a HTTP status code of 201 Created.

Common Status Codes Returned

Code	Description
201	Notification accepted
400	Malformed request
403	Forbidden
500	Server error

Receive information about an order

Get information about a specific order identified by its order number.

GET https://vfos-datahub.ascora.de/v1/orders/1337ASDF HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "meta":{
    "status":true
  },
  "data":{
    "orderActive":true,
    "orderId":"123-123",
    "orderDate":"2015-10-21T14:15:34+02:00",
    "customerId":123,
    "deliveryAddress":{
      "firstname":"Max",
      "lastname":"Mustermann",
      "company":"Ascora GmbH",
      "zip":"27777",
      "city":"Ganderkesee",
      "countryCode":"DE"
    },
    "amount":990,
    "currency":"EUR",
    "vat":{
      "type":"customer",
      "region":1,
      "countryCode":"DE",
      "vatPercentage":19,
      "taxAmount":158
    },
    "payType":"paypal",
    "payStatus":"paid",
    "cart":[
      {
        "amount":832,
        "productId":10,
        "qty":1
      }
    ],
    "orderTags":[
      "additionalOrderTag"
    ],
    "orderProperties":[
      {
        "key":"additionalPropertyKey",
        "value":"additionalPropertyValue"
      }
    ],
    "delivered":false,
    "updatePeriod":"2017-10-21T23:59:59+02:00"
  }
}

Request

The request is facing the customer's orders-subroute with specified order-id.

Request URL: GET /v1/customers/<user_id>/orders/<order_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Resource	string	User ID
order_id	No	Resource	string	Set to get information for a specific order.

Response

The response contains the order object with various attributes and objects.

Common Status Codes Returned

Code	Description
200	OK
400	Malformed request
404	User or order not found
500	Server error

Create a new order

Via this route a new order can be created

POST https://vfos-datahub.ascora.de/v1/customers/1337ASDF/orders HTTP/1.1

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /v1/customers/1337ASDF/orders/1337ASDF

{
  "meta":{
    "status":true
  },
  "data":{
    "order":{
      "orderActive":true,
      "orderId":"123-123",
      "orderDate":"2015-10-21T14:15:34+02:00",
      "customerId":123,
      "deliveryAddress":{
        "firstname":"Max",
        "lastname":"Mustermann",
        "company":"Ascora GmbH",
        "zip":"27777",
        "city":"Ganderkesee",
        "countryCode":"DE"
      },
      "amount":990,
      "currency":"EUR",
      "vat":{
        "type":"customer",
        "region":1,
        "countryCode":"DE",
        "vatPercentage":19,
        "taxAmount":158
      },
      "payType":"paypal",
      "payStatus":"paid",
      "cart":[
        {
          "amount":832,
          "productId":10,
          "qty":1
        }
      ],
      "orderTags":[
        "additionalOrderTag"
      ],
      "orderProperties":[
        {
          "key":"additionalPropertyKey",
          "value":"additionalPropertyValue"
        }
      ],
      "delivered":false,
      "updatePeriod":"2017-10-21T23:59:59+02:00"
    },
    "actions":[
      {
        "type":"redirect",
        "title":"Payment Confirmation Required",
        "url":"https://marketplace.vf-os.eu"
      }
    ]
  }
}

Request

The request contains multiple fields – required and non-required ones. Providing only required fields, a rudimentary order is being created.

Request URL: POST /v1/customers/<customer_id>/orders

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Resource	string	User ID
delivery_address_firstname	No	Body	string	Delivery address first name
delivery_address_lastname	No	Body	string	Delivery address last name
delivery_address_company	No	Body	string	Delivery address company
delivery_address_zip	No	Body	string	Delivery address zip
delivery_address_city	No	Body	string	Delivery address city
delivery_address_country_code	No	Body	string	Delivery address country code.
currency	Yes	Body	string	Currency of the order
pay_type	Yes	Body	string	pay type to be used
cart_n_product_id	Yes	Body	int	Product ID of item N
cart_n_product_qty	Yes	Body	int	Product ID of item N
order_tags	No	Body	string	Example: tag1;tag2
order_properties	No	Body	string	Example: key1;value1;;key2;value2

Response

The response contains the order-object in a success case. The API answers with a HTTP status code of 201 Created. Additionally, the Location-header contains a relative URI to the order-object.

The result may contain an array actions with more steps for the customer to complete the order. Instruct the customer to complete the order by eg redirect it to a given URI.

Common Status Codes Returned

Code	Description
201	Created
400	Malformed request
404	User not found
500	Server error

Request information about all assets

Get a list of all available vf-OS Assets with all its available information.

GET https://vfos-datahub.ascora.de/v1/products?per_page=10&page=3&category_type=specific_enabler&access_token=XXX HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "meta":{
    "status":true,
    "count":58,
    "page":1,
    "perPage":1
  },
  "data":[
    {
      "productId":96,
      "productNames":[
        {
          "langCode":"en-us",
          "name":"TestApp"
        }
      ],
      "screenShots":[
        {
          "hash":"2b89c337b94ee296997c8384b238d32c132290d1a8da14844dc944c3d9c29fa0",
          "langCode":"en-us",
          "publishData":"2017-05-24T17:57:46+02:00",
          "imageSizes":[
            {
              "url":"https://marketplace.vf-os.eu/media/products/96/screenshots/en-us/xkjhaskdh.png?h=2b89c337b94ee296997c8384b238d32c132290d1a8da14844dc944c3d9c29fa0",
              "fileInfo":{
                "contentType":"Unknown",
                "size":176799,
                "width":871,
                "height":490
              }
            }
          ]
        }
      ],
      "buyLinks":[
        {
          "langCode":"en-us",
          "url":"https://marketplace.vf-os.eu/en/checkout?addOnce=96"
        }
      ],
      "priceInfo":{
        "EUR":29.9,
        "USD":29.9,
        "CHF":29.9
      },
      "physicalProduct":false,
      "programVersions":[
        {
          "major":"2017",
          "version":1.1,
          "publishDate":"2017-07-12T00:00:00+02:00"
        },
        {
          "major":"2017",
          "version":1.0,
          "publishDate":"2017-05-24T00:00:00+02:00"
        }
      ],
      "categoryType":"enabler",
      "categoryNames":[
        {
          "langCode":"en-us",
          "name":"Security"
        }
      ]
    }
  ]
}

Request

Request URL: GET /v1/products?per_page=<per_page>&page=<page>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
page	No	Query	int	Page to show
per_page	No	Query	int	Assets to show per page
category_type	No	Query	String	Filter for category type

Response

The response contains an array of asset-objects. Via the per_page and page parameters the result can be browsed.

Common Status Codes Returned

Code	Description
200	OK
500	Server error

Request information about one specific asset

Get all available information about one specific vf-OS Asset.

GET https://vfos-datahub.ascora.de/v1/products/1337 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "meta":{
    "status":true
  },
  "data":{
    "productId":96,
    "productNames":[
      {
        "langCode":"en-us",
        "name":"TestApp"
      }
    ],
    "screenShots":[
      {
        "hash":"2b89c337b94ee296997c8384b238d32c132290d1a8da14844dc944c3d9c29fa0",
        "langCode":"en-us",
        "publishData":"2017-05-24T17:57:46+02:00",
        "imageSizes":[
          {
            "url":"https://marketplace.vf-os.eu/media/products/96/screenshots/en-us/xkjhaskdh.png?h=2b89c337b94ee296997c8384b238d32c132290d1a8da14844dc944c3d9c29fa0",
            "fileInfo":{
              "contentType":"Unknown",
              "size":176799,
              "width":871,
              "height":490
            }
          }
        ]
      }
    ],
    "buyLinks":[
      {
        "langCode":"en-us",
        "url":"https://marketplace.vf-os.eu/en/checkout?addOnce=96"
      }
    ],
    "priceInfo":{
      "EUR":29.9,
      "USD":29.9,
      "CHF":29.9
    },
    "physicalProduct":false,
    "programVersions":[
      {
        "major":"2017",
        "version":1.1,
        "publishDate":"2017-07-12T00:00:00+02:00"
      },
      {
        "major":"2017",
        "version":1.0,
        "publishDate":"2017-05-24T00:00:00+02:00"
      }
    ],
    "categoryType":"specific_enabler",
    "categoryNames":[
      {
        "langCode":"en-us",
        "name":"Security"
      }
    ]
  }
}

Request

The request is sent to the assets-route with the ID of the asset attached.

Request URL: GET /v1/products/<product_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
product_id	Yes	Resource	int	Product ID

Response

The response contains the asset representation if the asset was found.

Common Status Codes Returned

Code	Description
200	OK
404	Asset not found
500	Server error

Request binary file from a specific asset

Get the binary file of a specific vf-OS Asset.

GET https://vfos-datahub.ascora.de/v1/products/1337/binary HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/octet-stream

Request

The request is sent to the route specifying a distinct asset. Via a subroute the binary can be requested.

Request URL: GET /v1/products/<product_id>/binary

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
product_id	Yes	Resource	int	Product ID

Response

The response contains the binary file.

Common Status Codes Returned

Code	Description
200	OK
404	Binary or asset not found
500	Server error

Create a new vf-OS Asset

Create a new vf-OS Asset in the Marketplace. The created vf-OS Asset entry will be returned.

POST https://vfos-datahub.ascora.de/v1/products HTTP/1.1

Request

Request URL: POST /v1/products

Transfer Parameters

Name	Required	Parameter Type	Type	Description
product_names_en-us	Yes	Body	string	Product name in English
price_info_eur	Yes	Body	float	Price in EUR
physical_product	Yes	Body	string	true or false
category_id	Yes	Body	int	Category ID

Response

The response does contain the asset-object in a success case. The API answers with a HTTP status code of 201 Created. Additionally, the Location-header contains a relative URI to the asset-object.

Common Status Codes Returned

Code	Description
201	Created
400	Malformed request
500	Server error

Update information of a specific vf-OS Asset

Update a specific vf-OS Asset based on its product_id.

PATCH https://vfos-datahub.ascora.de/v1/products/1337 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Location: /v1/products/<product_id>

{
  "meta":{
    "status":true
  },
  "data":{
    "productId":96,
    "productNames":[
      {
        "langCode":"en-us",
        "name":"TestApp"
      }
    ],
    "screenShots":[

    ],
    "buyLinks":[
      {
        "langCode":"en-us",
        "url":"https://marketplace.vf-os.eu/en/checkout?addOnce=96"
      }
    ],
    "priceInfo":{
      "EUR":29.9,
      "USD":29.9,
      "CHF":29.9
    },
    "physicalProduct":false,
    "programVersions":[

    ],
    "categoryType":"enabler",
    "categoryNames":[
      {
        "langCode":"en-us",
        "name":"Security"
      }
    ]
  }
}

Request

Request URL: PATCH /v1/products/<product_id>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
product_id	Yes	Resource	int	Product ID
product_names_en-us	No	Body	string	Product name in English
price_info_eur	No	Body	float	Price in EUR
physical_product	No	Body	string	true or false
category_id	No	Body	int	Category ID

Response

The response does contain the updated asset-object in a success case.

Common Status Codes Returned

Code	Description
201	Created
400	Malformed request
500	Server error

Send usage data

Create new usage data for a specific customer.

POST https://vfos-datahub.ascora.de/v1/customers/1337ASDF/usagedata HTTP/1.1

HTTP/1.1 201 Created

Request

Request URL: POST /v1/customers/<user_id>/usagedata

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
user_id	Yes	Resource	string	User ID
category	Yes	Body	string	Category
action	Yes	Body	string	Action
label	No	Body	string	Label
value	No	Body	float	Value

Response

The response does not contain any content in the success case. The API answers with a HTTP status code of 201 Created.

Common Status Codes Returned

Code	Description
201	Created
400	Malformed request
404	User not found
500	Server error

Get all categories

Get all available categories of vf-OS Assets.

GET https://vfos-datahub.ascora.de/v1/categories     HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "meta":{
    "status":true,
    "count":5,
    "page":1,
    "perPage":1
  },
  "data":{
    "categories":[
      {
        "id":1,
        "names":[
          {
            "langCode":"de-de",
            "name":"Harmonization Map"
          },
          {
            "langCode":"en-us",
            "name":"Harmonization Map"
          }
        ],
        "sortingCoefficient":0,
        "type":"harmonization_map",
        "urlNames":[
          {
            "langCode":"de-de",
            "name":"Harmonization Map"
          },
          {
            "langCode":"en-us",
            "name":"Harmonization Map"
          }
        ]
      }
    ]
  }
}

Request

The request is facing the categories route.

Request URL: GET /v1/categories

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
page	No	Query	int	Page to show
per_page	No	Query	int	Assets to show per page

Response

The response contains the currently available categories.

Common Status Codes Returned

Code	Description
200	OK
500	Server error

Request manifest file for one specific asset

Get the manifest file for one specific vf-OS Asset.

GET https://vfos-datahub.ascora.de/v1/products/1337/manifest HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "meta":{
    "status":true
  },
  "data":{
    "manifest":{
      "vf-OS":true,
      "author":"Ifixall",
      "name":"bestapp",
      "description":"This is a fix all app for all vf-OS purposes, customers will be happy!",
      "dependencies":[
        "supportApp",
        "bestLibrary",
        "storageMongo"
      ],
      "binaryFile":"bestapp.exe",
      "frontendUri":"/web/index.html",
      "restUri":"/api/",
      "backendUri":"/web/backend.html",
      "configurationUri":"/web/settings.html",
      "iconHDUri":"/web/icon.png",
      "TobiasSeenThis":"?????",
      "AlwaysFun":"right?",
      "processEndpoints":{

      },
      "securityEndpoints":{

      },
      "vf-OS.compose.0.socket":true,
      "vf-OS.compose.1.serviceName":"myDB",
      "vf-OS.compose.1.image":"apache/couchdb",
      "vf-OS.compose.1.environment.COUCHDB":"http://myDB/db/api",
      "vf-OS.compose.1.environment.COUCHUSER":"dbUser",
      "vf-OS.compose.1.environment.COUCHPASS":"verySecret",
      "major":"19",
      "version":24,
      "publishDate":"2018-09-24T00:00:00+02:00",
      "boxshot":"https://vfos-octopus-api.ascora.de/media/abelssoft.de/products/1/screenshots/de-de/alpha.png?h=e1a09de6c16fb3b23316596d0657a4e2"
    }
  }
}

Request

The request is sent to the assets-route with the ID of the asset attached.

Request URL: GET /v1/products/<product_id>/manifest

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
product_id	Yes	Resource	int	Product ID

Response

The response contains the asset representation if the asset was found.

Common Status Codes Returned

Code	Description
200	OK
404	Asset or manifest not found
500	Server error

Create new customer

Create a new customer. The newly created customer object will be returned.

POST https://vfos-datahub.ascora.de/v1/customers HTTP/1.1

HTTP/1.1 201 Created

Request

The request contains multiple fields – required and non-required ones.

Request URL: POST /v1/paymentnotifications

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
email	Yes	Body	string	Email address
city	No	Body	string	City
company	No	Body	string	Company
firstname	Yes	Body	string	Firstname
language	Yes	Body	string	Language (in the form xx-xx)
lastname	Yes	Body	string	Lastname
street	No	Body	string	Street
zip	No	Body	string	Zip

Response

The response contains the customer-object in a success case. The API answers with a HTTP status code of 201 Created. Additionally, the Location-header contains a relative URI to the customer-object.

Common Status Codes Returned

Code	Description
201	Customer accepted
400	Malformed request
403	Forbidden
500	Server error

Create new version of a vf-OS Asset

Create a new version of a vf-OS Asset.

POST https://vfos-datahub.ascora.de/v1/products/1337/programversions HTTP/1.1

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "meta":{
    "status":true
  },
  "data":{
    "programVersions":[
      {
        "major":"19",
        "version":1,
        "publishDate":"2018-10-16T00:00:00+02:00"
      }
    ]
  }
}

Request

Request URL: POST /v1/products/<product_id>/programversions

Transfer Parameters

Information for using the partial upload

• Binary parts must be named with the following pattern: binary.zip.n where n is a number of 1 or larger

Name	Required	Parameter Type	Object Type	Description
product_id	Yes	Resource	int	Product ID
major	Yes	Body	string	Major version descriptor
version	Yes	Body	float	Version descriptor
publish_date	No	Body	date	Publish date
binary	Yes	Body	file	Binary
binary_hash	No	Body	string	Hash (MD5) of binary. Hash of concatenated file if using parts.
binary_part	No	Body	int	Number of this part. Must be 1 or larger
binary_part_max	No	Body	Int	Number of last part. Must be 1 or larger
languages	Yes	Body	string	Language (e.g. de,en)

Response

The response does contain the updated asset-object in a success case.

Common Status Codes Returned

Code	Description
200	Binary part accepted, continue with next part
201	Created
400	Malformed request
500	Server error

vf-OS Assets

FIWARE Generic Enablers

FIWARE Generic Enablers component is composed of solutions that offer reusable and common shared functionalities serving multiple usecases in various sectors that have been developed by FIWARE project. These solutions are termed as Generic Enablers (GEs) and provide functionalities in different domains such as IoT, data, context management, interfaces to network/devices, cloud hosting, security etc. The functionalities provided by these enablers can be used for realisation of some of the core features of vApps to implement their business requirements.

All the Generic Enablers are technically and functionally diverse and have their own API specifications. The APIs of all the Generic Enablers are provided as API blueprints that has been defined using APIARY tools. The details of each of the enabler can be accessed through FIWARE Catalogue. In this specification, we will provide two parts:

1. API common to all GEs - these will be common functionalities that are envision to be developed in the scope of vf-OS project to enhance the existing functionalities of GEs
2. API specific to selected GE - these are the functionalities provided by GE and as described in their original documentation.

The URL is presented in the following format:

http://dev.vfos.eu/fiware-generic-enablers/

Create a Configuration

Create a configuration for a specific enabler.

POST /commons HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "enablerConfiguration":"configurationId",
  "configurations":{
    "config1":"configValue1"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{

  }
}

Request

The request contains all necessary information to create configurations of one enabler. It also contains multiple fields, but only enablerConfiguration is required.

Request URL: POST /commons

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerConfiguration	Yes	Body	string	Identification of the configuration
configurations	No	Body	Object	Configurations of the enabler

Response

The response contains the status of creating the connection. If it returns one error, it will also return the error description.

Get configurations from a specific Enabler

Retrieve all configuration parameters and its values.

GET /commons/<enablerConfiguration> HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":[
    {
      "config1":"ConfigValue1",
      "config2":"ConfigValue2"
    }
  ]
}

Request

The request contains enablerConfiguration, which is a mandatory field.

Request URL: GET /commons/<enablerConfiguration>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerConfiguration	Yes	Resource	string	Identification of the configuration

Response

The response contains the status (success or error). If the status is success, it also returns the enabler's configurations.

Get a specific configuration from a specific Enabler

Retrieve a configuration parameter and its value.

GET /commons/<enablerConfiguration>/<configurationParameter> HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{
    "config1":"ConfigValue1"
  }
}

Request

The request contains enablerConfiguration and configurationParameter, which are mandatory fields.

Request URL: GET /commons/<enablerConfiguration>/<configurationParameter>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerConfiguration	Yes	Resource	string	Identification of the configuration
configurationParameter	Yes	Resource	string	Name of the parameter

Response

The response contains the status (success or error). If the status is success, it also returns the enabler's specific configuration.

Update a specific configuration from a specific Enabler

Update a configuration value.

PUT /commons/<enablerConfiguration>/<configurationParameter> HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "config1":"configNewValue"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status":"success",
  "data":{

  }
}

Request

The request contains enablerConfiguration and configurationParameter, which are mandatory fields.

Request URL: PUT /commons/<enablerConfiguration>/<configurationParameter>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
enablerConfiguration	Yes	Resource	string	Identification of the configuration
configurationParameter	Yes	Resource	string	Name of the parameter

Response

The response contains the status (success or error). If the status is error, it also returns the error message.

FIWARE Manufacturing Enablers

FIWARE Manufacturing Enablers provide solutions in the domain that are not addressed specifically in vf-OS, such as IoT enablers, supply chain enablers, collaborative enablers, and data analytics enablers.

In this specification, common API endpoints to add or update a configuration of a Manufacturing Enabler (ME) will be provided.

General URL

Requests are formatted with the following common variables.

Name	Example	Description
hostname	me.vfos.com	Specifies the server host
port	9443	Specifies the server port
base_uri	/api	Specifies the base URI
version	1.0.0	API version
resource_uri	/menablerconfigurations	The uri of the resource

The URL is presented in the following format:
https://<hostname>:<port>/<base_uri>/<version>/<resource_uri>

The left part of the URL, up to the resource_uri, is common to all the ME API endpoints, so it will not be repeated in every interface in this documentation. The user should assume this should be prefixed to every endpoint:

Create Configuration

This API provides a capability to define the configuration parameters of the FITMAN Specific Enablers for admin users. The parameters include database configurations, security constraints, server configurations, or other business constraints as necessary.

POST /api/v0.11/menablerconfigurations HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "enablerConfiguration":"idEnablerConfigurationCAM",
  "configurations":[
    {
      "businessContstraintParamKey0":"businessContstraintValue0",
      "businessContstraintParamKey1":"businessContstraintValue1",
      "businessContstraintParamKey2":"businessContstraintValue2"
    }
  ]
}

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

{
  "enablerConfiguration":"idEnablerConfigurationCAM",
  "configurations":[
    {
      "businessContstraintParamKey0":"businessContstraintValue0",
      "businessContstraintParamKey1":"businessContstraintValue1",
      "businessContstraintParamKey2":"businessContstraintValue2"
    }
  ]
}

Request

Request URL : POST /menablerconfigurations

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
idEnablerConfiguration	Yes	Body	string	Identification of the configuration
configurations	Yes	Body	[string]	JSON object containing the key/value of the configurations

Response

If successful, the response contains the newly created object as entity in the body

Common status codes returned

Code	Description
201	Created
403	Unauthorized. The credentials provided are not valid.

List configurations

This API provides a capability to list all configurations parameters of the FITMAN Specific Enablers.

GET /api/v0.11/enablerconfigurations/configurationCamME HTTP/1.1

HTTP/1.1 200 OK
Date: Tue, 05 Sep 2017 14:25:17 GMT
Content-Type: application/json; charset=utf-8

{
  "configurations":[
    {
      "businessContstraintParamKey0":"businessContstraintValue0",
      "businessContstraintParamKey1":"businessContstraintValue1",
      "businessContstraintParamKey2":"businessContstraintValue2"
    }
  ]
}

Request

Request URL : Get /enablerconfigurations/<idEnablerConfiguration>

JSON Request Parameters

Name	Required	Parameter Type	Object Type	Description
idEnablerConfiguration	Yes	Ressource	string	Identification of the configuration

Response

Returns Successful response with the a list of available parameters in the body.

Common status codes returned

Code	Description
200	Success

Update configuration

This API provides for admin users a capability to update the configuration parameters of the FITMAN Specific Enablers.

PUT /api/v0.11/enablerconfigurations/configurationCamME HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "configurations":[
    {
      "businessContstraintParamKey0":"businessContstraintValue0",
      "businessContstraintParamKey1":"businessContstraintValue1",
      "businessContstraintParamKey2":"businessContstraintValue2"
    }
  ]
}

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

{
  "configurations":[
    {
      "businessContstraintParamKey0":"businessContstraintValue0",
      "businessContstraintParamKey1":"businessContstraintValue1",
      "businessContstraintParamKey2":"businessContstraintValue2"
    }
  ]
}

Request

Request URL : PUT /enablerconfigurations/<idEnablerConfiguration>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
idEnablerConfiguration	Yes	Resource	string	Identification of the configuration
configurations	Yes	Body	string	JSON object containing the key/value of the configurations

Response

Returns Successful response with the updated parameter in the body.

Common status codes returned

Code	Description
200	Success
403	Unauthorized. The credentials provided are not valid.
404	Not Found. The resource to be updated does not exist.

3DScan Manufacturing Enabler

This ME offers comprehensive modules for 3D Visualisation of high density/high resolution files consisting of millions of points in the format of Point clouds(.txt) and Mesh(.stl). Additionally, it provides the management interface for 3D file storage with relational database. There are two open source components provided by the Specific Enabler: Storage and visualisation. The Specific Enabler aims at offering assistance for performing quality controls and an intuitive visualisation decision support system to determine if the analysed manufactured part must be accepted or rejected.

Request 1

/3dscan/v1/sqlrest/webgl : This service helps to view the database structure to check the newly added file.

Request URL:
http GET /3dscan/v1/sqlrest/webgl HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns XML file corresponding to the database content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 2

/3dscan/v1/sqlrest/webgl/{imageObjectId} : This service helps to view the specific object already uploaded to the 3DScan database.

Request URL:
http GET /3dscan/v1/sqlrest/webgl/{imageObjectId} HTTP/1.1 Content-Type: application/json; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
imageObjectId	Yes	URL	int	Object to fetch

Response

Returns XML file corresponding to the object imageObjectId.

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

Request 3

/3dscan/v1/FitmanGL/rest/get/id_canvas/{imageObjectId} : The return data is a JavaScript code which could be integrated in any web page to display the 3D file. E.g. the usage of displaying the 3D file as aforementioned interfaces, could be in javascript code:

<script
src="http://localhost:8080/FitmanGL/rest/get/id_canvas/your image
ID added in the database" type="text/javascript"></script>

Request URL:
http GET /3dscan/v1/FitmanGL/rest/get/id_canvas/{imageObjectId} HTTP/1.1 Content-Type: application/json; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
imageObjectId	Yes	URL	int	Object to fetch

Response

Returns Javascript content file corresponding to the object source code of the imageObjectId.

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

Request 4

/3dscan/v1/FitmanGL/rest/post/upload : Send POST with the 3D file to upload a new file to the 3DScan database

Request URL:
http POST /3dscan/v1/FitmanGL/rest/post/upload HTTP/1.1 Content-Type: multipart/form-data; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
file	Yes	BODY	File	Object to upload

Response

Returns 200. OK

Common status codes returned

Code	Description
200	OK
400	Bad request. Invalid request or validation error.
404	Not Found. Requested API does not exist.

Collaborative Asset Management (CAM) Manufacturing Enabler

This ME is a web-based, integrated platform for the management of Virtualised Assets in the scope of service-oriented Manufacturing Ecosystems. Targeted at the Virtual Factory domain, and based on open standards like Resource Description Framework (RDF), Web Ontology Language (OWL2) and Universal Service Description Language (LinkedUSDL), it is delivered as a web portal in order to maximise its collaborative nature.

FITMAN CAM exposes its own public, proprietary REST-based web API. By means of API calls, the reference ontology, the asset repository and the service registry can be queried by external applications. Note that only read operations are supported.

Request 1

/cam/v1/classes : This service helps to get all classes of the used ontology.

Request URL:
http GET /3dscan/v1/classes HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns Json file corresponding to all classe content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 2

/cam/v1/classes/{class}/assets/ : This service helps to get all assets of a specific class defined in the parameter {class}.

Request URL:
http GET /3dscan/v1/classes/{class}/assets/ HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns Json file corresponding to all assets belonging to {class} content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 3

/cam/v1/services/public/ : This service helps to get all public services.

Request URL:
http GET /3dscan/v1/services/public/ HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns Json file corresponding to all public services.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Request 4

/cam/v1/services/public/{service} : This service helps to get all details of a specific service {service}.

Request URL:
http GET /cam/v1/services/public/{service} HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns Json file corresponding to all details of the required service {service}.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Collaborative Business Process Management (CBPM) Manufacturing Enabler

This ME is a web-based, integrated platform for the semantically-enhanced design, execution and monitoring of Business Processes in the scope of service-oriented Manufacturing Ecosystems. Targeted at the Virtual Factory domain, and based on open standards like Business Process Model and Notation (BPMN) 2.0, it is delivered as a web portal in order to maximise its collaborative nature.

Request 1

/cbpm/v1/sqlrest/webgl : This service helps to view the database structure of the CBPM.

Request URL:
http GET /cbpm/v1/sqlrest/webgl HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns XML file corresponding to the database content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Shopfloor Data Collection Manufacturing Enabler

This ME is dedicated to the collection of data from the shop floor. It is developed to act as the middleware between the data producers in the shop floor and the data consumers. At the same time this SE also decouples the event producers from events consumers to provide flexibility in the processing of production data and further dispatch the events to event processing engines such as Secure event Management in the scenario of FITMAN. The objectives of this ME are: Capture and acquire data from tagged objects (eg RFID) and Capture and acquire data from networks of [wireless] sensors.

Request 1

/cfdc/v1/sqlrest/webgl : This service helps to view the database structure of the CBPM.

Request URL:
http GET /cfdc/v1/sqlrest/webgl HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns XML file corresponding to the database content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Data Interoperability Platform Services Manufacturing Enabler

The FITMAN " Data Interoperability Platform Services" Specific Enabler (FITMAN-DIPS) is a web-based platform for the management of Data Interoperability services in the sope of the exploitation of the interoperability service.

Request 1

/dips/v1/sqlrest/webgl : This service helps to view the database structure of the FITMAN-DIPS.

Request URL:
http GET /dips/v1/sqlrest/webgl HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns XML file corresponding to the database content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Supply Chain & Business Ecosystem Apps Manufacturing Enabler

The FITMAN "Supply Chain & Business Ecosystem Apps" Specific Enabler (FITMAN-SCApp) is a web-based application for exploiting ecosystem Tangible and Intangible Assets in relation with application in Collaborative Capacity Scheduling and Team Building.

Request 1

/scapp/v1/sqlrest/webgl : This service helps to view the database structure of the FITMAN-SCApp.

Request URL:
http GET /scapp/v1/sqlrest/webgl HTTP/1.1 Content-Type: application/json; charset=utf-8

Response

Returns XML file corresponding to the database content.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

Dynamic Content Manager Enabler (DCME)

The main functionality of the Dynamic Content Manager Enabler (DCME) is to provide an easy and user-friendly GUI to manage documents. When an enterprise repository structure is updated, a dynamic reorganisation in the structure of the documents is generated. So, this Dynamic Content Manager will be automatic and synchronised with the possible changes in the enterprise organisation.

Request 1

/dcme/v1/alfresco/s/api/folders : This service helps to create the structure folders needed by the manager of the DCME Enabler.

Request URL:
http POST /dcme/v1/alfresco/s/api/folders HTTP/1.1 Content-Type: application/json; charset=utf-8

Request Parameters

Name	Required	Parameter Type	Object Type	Description
payload	Yes	BODY	string	Json structure to create

Response

Returns 200. OK.

Common status codes returned

Code	Description
200	OK
404	Not Found. Requested API does not exist.

vf-OS Enablers

ENTER DESCRIPTION HERE

Enabler 1 - Get all Enabler's Configurations

GET /api/vf-os-enabler/v1/enabler/1/configurations HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result":"success",
  "documents":[
    {
      "_id":"5988518d34cfea1307ecf296",
      "__v":0,
      "created_at":"2017-08-07T11:39:57.094Z",
      "body":[
        {
          "mongoport":"123"
        }
      ],
      "comment":"This is the first config version",
      "parent":null,
      "active":false,
      "enablerid":"1",
      "version":1
    },
    {
      "_id":"2008518d34cfea1307rty876",
      "__v":0,
      "created_at":"2017-08-07T12:00:00.000Z",
      "body":[
        {
          "mongoport":"123"
        },
        {
          "loglevel":"debug"
        }
      ],
      "comment":"This is the second config version based on the previous one",
      "parent":1,
      "active":true,
      "enablerid":"1",
      "version":2
    }
  ]
}

Use this API call whenever is needed to retrieve all configurations related to one enabler.

Request

Request URL : GET /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/configurations

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
api_version	Yes	Resource	string	Identifies the API version that will be used for the request
enabler_id	Yes	Resource	string	Identifies the Enabler from the enablers pool
filter	No	Query	String	set active to retrieve the active configuration set last to retrieve last configuration set first to retrieve first configuration set next to retrieve the next configuration version id in DB

Return Payload

The API response will contain a JSON document with the property result: success, error or empty and the documents with the enabler's configurations (if found).

Return Codes

Code	Description
200	Configurations found
404	Configurations not found
422	Unprocessable entity if the filter is not set in the write way
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 1 - Get Enabler's specific configuration

GET /api/vf-os-enabler/v1/enabler/1/configurations/2 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result":"success",
  "documents":[
    {
      "_id":"2008518d34cfea1307rty876",
      "__v":0,
      "created_at":"2017-08-07T12:00:00.000Z",
      "body":[
        {
          "mongoport":"123"
        },
        {
          "loglevel":"debug"
        }
      ],
      "comment":"This is the second config version based on the previous one",
      "parent":1,
      "active":true,
      "enablerid":"1",
      "version":2
    }
  ]
}

Use this API call whenever is needed to retrieve one single configuration version.

Request

Request URL : GET /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/configurations/<configuration_version>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
api_version	Yes	Resource	string	Identifies the API version that will be used for the request
enabler_id	Yes	Resource	string	Identifies the Enabler from the enablers pool
configuration_version	Yes	Resource	string	Identifies the configuration version from the configurations pool

Return Payload

The API response will contain a JSON document with the query result: success, error or empty and the documents with the enabler's configuration queried.

Return Codes

Code	Description
200	Configuration Found
404	Configuration Not Found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 1 - Activate Enabler's Configuration

PATCH /api/vf-os-enabler/v1/enabler/1/configurations/2 HTTP/1.1
Content-Type: application/json; charset=utf-8

[
  {
    "o":"replace",
    "k":"active",
    "v":true
  }
]

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "result":"success"
}

Use this API call whenever is needed to activate the configuration version.

Request

Request URL : PATCH /api/vf-os-enabler/v1/enabler/<enabler_id>/configurations/<configurations_version>

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
api_version	Yes	Resource	string	Identifies the API version that will be used for the request
enabler_id	Yes	Resource	string	Identifies the Enabler from the enablers pool
configuration_version	Yes	Resource	string	Identifies the configuration versions from the configurations pool
Operation	Yes	Body entity	JSON Object	An object which describes the operation to be made contains the following attributes: o: Operation to be made (eg set replace to replace th k property with the v value) k: Key to be used for the operation v: Value to be used for the operation

Return Payload

The API response will contain a JSON document with the query result: success or error.

Return Codes

Code	Description
200	Configuration Activated
404	Configuration Not Found
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 1 - Create Enabler Configuration

POST /api/vf-os-enabler/v1/enabler/1/configurations/ HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "version":3,
  "active":false,
  "parent":null,
  "enablerid":"1",
  "comment":"This is the third config version",
  "body":{
    "my_key":"my_value"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result":"success"
}

Use this API call whenever is needed to create a new configuration version for one enabler.

Request

Request URL : POST /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/configurations

Transfer Parameters

Name	Required	Parameter Type	Object Type	Description
api_version	Yes	Resource	String	Identifies the API version that will be used for the request
enabler_id	Yes	Resource	String	Identifies the Enabler from the enablers pool
Enabler Configuration	Yes	Body entity	JSON Object	This configuration contains the following attributes: version: The configuration version that will be created. parent: For historical purposes the parameter represents the version of the parent configuration file which the n ew one is based on enablerId: Enabler identification which the new configuration to be created belongs to. comment: Configuration comment body: JSON document where the custom configuration parameters are.

Return Payload

The API response will contain a JSON document with the query result: succes or error.

Return Codes

Code	Description
201	Configuration created successfully
500	Internal Server Error - There was an unexpected error at some point during the processing of the request.