NAV Navbar
http

vf-OS Platform

Platform

The vf-OS Platform component provides two fundamental services:

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 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 and PubSub

JavaScript library to simplify the use of amqplib and RabbitMQ.

The messaging and pub sub functions are provided through a library. The instructions from this documentation are focused for JavaScript applications. For Java applications, please use this link lib-messaging-pub-sub-java.

AMQP & RabbitMQ

The message broker has a loosely coupled architecture, which allows the components of the system to use the name rather than their location/address. This can only be possible because the broker (RabbitMQ) does all the messaging management. It receives the messages produced by the producers/publishers and will deliver them to the consumers or another broker. In vfOS project, the message broker will use Advanced Message Queuing Protocol (AMQP), that is an open standard that defines a protocol for components to exchange messages. It is a specification that defines the semantics of an interoperable messaging protocol [1]. In [1] you can find a comparison between AMQP and other message protocols.

Install

In this library's folder run

npm install

Import

vfosMessagingPubsub = require('lib-messaging-pub-sub-js');

Initialize

communicationObject = new vfosMessagingPubsub("broker.address.com", "username", "componentPassword", ["example.key.*", "example.anotherkey.logs"]);

Login and Registry happen automatically on initialization.

For messaging data middleware, each component has a private queue which is listening to the routingkey: eu.vfos.componentName when the component creates the data middleware component.

Avaliable Methods

Upon initializing a vfosMessagingPubsub object, the following methods become avaliable for use

Each of these methods return a promise

login()

Connect to the messaging system

logout()

Disconnect from the messaging system

register(keys)

Register on the messaging system, create our queues and subscribe to topic keys (string array)

After registering, messages messages will be saved even if the user is offline

unregister()

Unregister from the messaging system and delete our queues

removeSubscription(keys)

Remove the PubSub subscriptions of topic keys (string array)

addSubscription(keys)

Add the PubSub subscriptions to topic keys (string array)

sendPrivateMessage(prefix, dest, content)

Send a private message to a component dest (string) in a location prefix (string) with content (multitype)

sendPublication(key, content)

Publish a message on a topic key (string) with content (multitype)

registerPrivateMessageReceiver(callback)

Check our messaging queue for private messages

Provide a callback (function) for handling each retrieved message object

registerPublicationReceiver(callback)

Check our PubSub queue for public messages

Provide a callback (function) for handling each retrieved message object

Message object

Received messages are resolved in the following format

element type description
routingKey string String with the routing key of the message
id string Identification of the sender
content blob Content of the message
timestamp number Unix time of sending
length number Length of the message

Each of these functions returns a promise that will resolve if its execution is successful or get rejected otherwise

Security Integration

This library creates three independent channels: * MessagingChannel - Channel for message data middleware * PubsubChannel - Channel for pubsub data middleware * AnnouncementChannel - Channel that broadcasts announcements

The channel will be closed if the user doesn't have permission to perform one action. E.g. if the user tries to write a message queue and the component only has permission to read from that queue, the messaging channel will be close due to security measures.

When the communication object is created, the component requires the following permissions: * Messaging data middleware * MessagingChannel * read from topic : eu.vfos. * Pubsub data middleware * PubsubChannel * read from topics that were specified when the component creates the communication object * AnnouncementChannel * write to all topics starting with (with wildcard): eu.vfos.announcements

References

[1] - RabbitMQ

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

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
body Yes Body JSON Object Database name to be created

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 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/<databaseName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName 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

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

Request

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

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName 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

{
  "list": [
    "myview4",
    "viewfilms4",
    "myview",
    "myview3",
    "myview5"
  ],
  "error": {
    "code": null,
    "message": null
  }
}

Request

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

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName 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 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": "mytable1",
    "columns": [
    {
      "name": "colstring",
      "type": "varchar"
    },
    {
      "name": "colint",
      "type": "integer"
    }
  ],
  "constraints": [
    {
      "primary_key": {
        "columns": [
          "colint"
        ],
        "name": "const_pri1"
      },
      "unique": {
        "columns": [
          "colstring"
        ],
        "name": "const_uniq1"
      },
     "foreign_key": {
        "columns": [
          "colstring"
        ],
        "name": "const_for1",
        "on_delete": "CASCADE",
        "on_update": "CASCADE",
        "referenced_columns": [
          "colstring"
        ],
        "referenced_table_name": "test111"
      }
    }
  ]
}

HTTP/1.1 201 CREATED

Request

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

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String The ID/Name of the database
body Yes Body JSON Object Schema of the table.

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/<databaseName>/tables/<tableName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String The ID/Name of the database
tableName 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

EXAMPLE 1
{
  "new_table_name": "mytable1_new"
}

EXAMPLE 2
{
  "column_rename": {
    "new_name": "colint1",
    "old_name": "colint"
  }
}

EXAMPLE 3
{
  "columns_to_add": [
    {
      "allow_null": false,
      "default": "0",
      "name": "col3",
      "size": 0,
      "type": "integer"
    },
    {
      "allow_null": false,
      "default": "string",
      "name": "col4",
      "size": 20,
      "type": "varchar"
    }
  ]
}

EXAMPLE 4
{
  "columns_to_alter": [
    {
      "allow_null": false,
      "default": "string",
      "name": "col3",
      "size": 20,
      "type": "varchar"
    },
    {
      "allow_null": false,
      "default": "string",
      "name": "col4",
      "size": 200,
      "type": "varchar"
    }
  ]
}

EXAMPLE 5
{
  "columns_to_delete": [
    "col3", "col4"
  ]
}

EXAMPLE 6
{  
  "constraints_to_add": [
    {
      "primary_key": {
        "columns": ["colint","colstring"],
        "name": "constr22xxxx"
      }
    }
  ]
}

EXAMPLE 7
{  
  "constraints_to_add": [
    {
      "foreign_key": {
        "columns": ["colint1","colstring"],
        "name": "constr111",
        "on_delete": "CASCADE",
        "on_update": "CASCADE",
        "referenced_columns": ["colint","colstring"],
        "referenced_table_name": "test3"
      },
      "unique": {
        "columns": ["colint1"],
        "name": "constr333"
      }
    }
  ]
}

HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<databaseName>/tables/<tableName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
body Yes Body JSON Object Alteration schema for the 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. Table altered.
400 Bad request. There are errors in the specification of the alteration of the table
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.

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_columns": [
    "micolumna"
  ],
  "view_definition_query": "select * from test.test",
  "view_name": "myview33"
}

HTTP/1.1 201 CREATED

Request

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

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
body Yes Body JSON Object Definition of the view.

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 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/<databaseName>/views/<viewName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
viewName 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 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_columns": [
    "micolumna"
  ],
  "view_definition_query": "select * from test.test"
}
HTTP/1.1 200 OK

Request

Request URL: PUT /rel/databases/<databaseName>/views/<viewName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
viewName Yes Resource String Identifier for the targeted view
body Yes Body JSON Object Definition of the 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. 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.

Catalog Relational Table Indexes

Gets the list of indexes of a given relational database table.

GET https://api.vfos.com:7777/3.0/rel/databases/myRelationalDatabase/tables/myTable/views HTTP/1.1
HTTP/1.1 200 Success
Content-Type: application/json; charset=utf-8
{
  "list": [
    "idx2",
    "idx1"
  ],
  "error": {
    "code": null,
    "message": null
  }
}

Request

Request URL: GET /rel/databases/<databaseName>/tables/<tableName>/indexes

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table

Response

Returns a status code. In case of success it also returns a catalog (list) of the indexes of the database 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.

Describe Relational Index

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

GET https://api.vfos.com:7777/3.0//rel/databases/<databaseName>/tables/<tableName>/indexes/myIndex HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "definition_query": "CREATE INDEX idx1 ON test.test USING btree (upper((colstring)::text) DESC NULLS LAST, colint NULLS FIRST) WHERE (colint > 0)",
  "error": {
    "code": null,
    "message": null
  }
}

Request

Request URL: GET /rel/databases/<databaseName>/tables/<tableName>/indexes/<indexName>

Transfer Parameters

Parameter In Type Required Description
databaseName path string true Database name
tableName path string true Table name
indexName path string true Index name

Response

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

Common status codes returned

Status Meaning Description Schema
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.

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

{
  "col_def": [
    {
      "columns_expresion": "upper(col1)",
      "nulls": "FIRST",
      "ordering": "ASC"
    }
  ],
  "index_name": "string",
  "partial_index_definition_query": "col1 > 0"
}
HTTP/1.1 201 CREATED

Request

Request URL: POST /rel/databases/<databaseName>/tables/<tableName>/indexes

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
body Yes Body String Schema of 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 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.

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/<databaseName>/tables/<tableName>/indexes/<indexName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
indexName 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
400 Bad request. Invalid database name supplied.
401 Unauthorized. The credentials provided are not valid.
403 Forbidden. The user has not enough privileges to perform this action.
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.

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/tables/myTable HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "col_def": [
    {
      "default": null,
      "name": "colstring",
      "type": "character varying",
      "size": 0,
      "allow_null": true
    },
    {
      "default": null,
      "name": "colint",
      "type": "integer",
      "size": 0,
      "allow_null": false
    }
  ],
  "constraints_def": [
    {
      "constraint_name": "const_pri1x",
      "constraint_definition": "PRIMARY KEY (colint)"
    },
    {
      "constraint_name": "const_uniq1x",
      "constraint_definition": "UNIQUE (colstring)"
    },
    {
      "constraint_name": "const_for1x",
      "constraint_definition": "FOREIGN KEY (colstring) REFERENCES test.test111(colstring) ON UPDATE CASCADE ON DELETE CASCADE"
    }
  ],
  "error": {
    "code": null,
    "message": null
  }
}

Request

Request URL: GET /rel/databases/<databaseName>/tables/<tableName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName 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
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.

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_query": " SELECT test.colstring AS micolumna,\n    test.colint AS niotra\n   FROM test.test\n  WHERE (test.colint > 4);",
  "error": {
    "code": null,
    "message": null
  }
}

Request

Request URL: GET /rel/databases/<databaseName>/views/<viewName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
viewName 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
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.

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

[
    {
      "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


Request

Request URL: POST /rel/databases/<databaseName>/tables/<tableName>/rows

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
body 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 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
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.

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?filter=Name%20%3D%20'John'%20and%20Age%20%3C%2018 HTTP/1.1
Content-Type: application/json; charset=utf-8

HTTP/1.1 200 OK

Request

Request URL: DELETE /rel/databases/<databaseName>/tables/<tableName>/rows

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
filter No Query 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
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.

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?filter=Name%20%3D%20'John'%20and%20Age%20%3C%2018 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
   "colstring":"value5",
   "colint":"5"
}
HTTP/1.1 200 OK

Request

Request URL: PATCH /rel/databases/<databaseName>/tables/<tableName>/rows

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
body Yes Body JSON Array List of values to be updated. The format is a JSON set of column_name:value. For instance {"col1":"value11", "col2":"value21"}.
filter No Query 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
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.

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

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

Request

Request URL (tables): GET /rel/databases/<databaseName>/tables/<tableName>/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/<databaseName>/views/<viewName>/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
databaseName Yes Resource String Identifier for the targeted database
tableName Yes Resource String Identifier for the targeted table
viewName Yes Resource String Identifier for the targeted view
query_columns_specification No Query Array of strings 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
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.

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. The backend storage service is MongoDB. The REST API is RESTHeart(https://restheart.org/). You can find much more detailed documentantion about the API here: (https://restheart.org/learn/tutorial/).

Create or update document-oriented Database

Creates or updates a document-oriented database.

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

{
 "desc":"My first db"
}
HTTP/1.1 200 OK
...
ETag: 5c3388f865dfb7437c908a96
...

Request

Request URL: PUT /<databaseName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
body No Body JSON Object Description of the database

Response

Returns a status code and in case of error, an error message in the response body. If successfull returns also an eTag.

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.
406 Unacceptable. There was any error in the parameters.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get a document-oriented Database

Gets a document-oriented database.

GET https://api.vfos.com:7777/myDocumentDatabase HTTP/1.1
Content-Type: application/json; charset=utf-8

HTTP/1.1 200 OK
...
ETag: 5c3388f865dfb7437c908a96
...
{"_embedded":[],"_id":"dbname","_etag":{"$oid":"5c3388f865dfb7437c908a96"},"_size":0,"_total_pages":0,"_returned":0}

Request

Request URL: GET /<databaseName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database

Response

Returns a status code and in case of error, an error message in the response body. If successfull returns also information about the database in Json format, including it's eTag.

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.
406 Unacceptable. There was any error in the parameters.
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/myDocumentDatabase --header If-Match:"5af1949ca7b11b00053ecc5d" HTTP/1.1
HTTP/1.1 204 No Content

Request

Request URL: DELETE /<databaseName> --header If-Match:<eTag>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String The Name of the database to be deleted
If-Match Yes Header String The eTag returned at creation or getting 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
204 No Content. The database was succesfully deleted.
401 Unauthorized. The credentials provided are not valid.
403 Forbidden. The user has not enough privileges to perform this action.
404 Database not found
412 Precondition failed. The provided eTag does not match with the database.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Catalog Document-oriented Database Collections

GET https://api.vfos.com:7777/myDocumentDatabase HTTP/1.1
Content-Type: application/json; charset=utf-8

HTTP/1.1 200 OK
...
ETag: 5c3388f865dfb7437c908a96
...
{"_embedded":[{"_id":"myCollection","desc":"My first col","_etag":{"$oid":"5c34b6b895fe130005aa558e"}},{"_id":"col2","_etag":{"$oid":"5c34b6e795fe130005aa5590"},"desc":"My sec col"}],"_id":"dbname","desc":"My first db","_etag":{"$oid":"5c33929d95fe1300058cd011"},"_size":2,"_total_pages":1,"_returned":2}

Request

Request URL: GET /<databaseName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database

Response

Returns a status code and in case of error, an error message in the response body. If successfull returns also the existing collections as well as information about the database in Json format, including it's eTag.

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.
406 Unacceptable. There was any error in the parameters.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create or update Document-oriented Collection

Creates or updates a collection in a given document-oriented database.

PUT https://api.vfos.com:7777/myDocumentDatabase/myCollection HTTP/1.1 
Content-Type: application/json; charset=utf-8

{
 "desc":"My first col"
}
HTTP/1.1 200 OK
...
ETag: 5c34b8a295fe130005aa5591
...

Request

Request URL: PUT /doc/<databaseName>/<collectionName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String 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
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
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get a document-oriented collection

Gets a collection in a document-oriented database.

GET https://api.vfos.com:7777/myDocumentDatabase/myCollection HTTP/1.1
Content-Type: application/json; charset=utf-8

HTTP/1.1 200 OK
...
ETag: 5b85570ddaafe81163861638
...
{"_embedded":[{"_id":{"$oid":"5b85570ddaafe81163861638"},"neme":"doc2","rating":"super cool \ntoo","_etag":{"$oid":"5b85570da7b11b0005b8e304"}}],"_id":"myCollection","desc":"My first col","_etag":{"$oid":"5c34c87e95fe130005aa5592"},"_returned":1}

Request

Request URL: GET /<databaseName>/<collectionName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection

Response

Returns a status code and in case of error, an error message in the response body. If successfull returns also information about the collection in Json format, including it's eTag and list of documents.

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.

Drop Document-oriented Collection

Drops an existing collection of a given document-oriented database. http DELETE https://api.vfos.com:7777/myDocumentDatabase/myCollection --header If-Match:"5b85570ddaafe81163861638" HTTP/1.1

HTTP/1.1 204 No Content

Request

Request URL: DELETE /<databaseName>/<collectionName> --header If-Match:<eTag>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String The Name of the database to be deleted
collectionName Yes Resource String Name of the collection
If-Match Yes Header String The eTag returned at creation or getting 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
204 No Content. The collection was succesfully deleted.
401 Unauthorized. The credentials provided are not valid.
403 Forbidden. The user has not enough privileges to perform this action.
404 Database not found
412 Precondition failed. The provided eTag does not match with the collection.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Create or update a Document-oriented Index of a Collection

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

PUT https://api.vfos.com:7777/myDocumentDatabase/myCollection/_indexes/myindex HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "keys":{"prop":1}, 
    "ops":{"unique":true, "sparse":true}
}
HTTP/1.1 201 CREATED

Request

Request URL: PUT /doc/<databaseName>/<collectionName>/_indexes/<indexName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
indexName Yes Resource String 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.
ops 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
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/myDocumentDatabase/myCollection/_indexes/myindex HTTP/1.1
Content-Type: application/json; charset=utf-8

HTTP/1.1 204 No Content

Request

Request URL: DELETE /doc/<databaseName>/<collectionName>/_indexes/<indexName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
indexName Yes Resource String Name of 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
204 No Content. The index was succesfully deleted.
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
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Get the indexes of a collection

Gets the indexes of a collection in a document-oriented database.

GET https://api.vfos.com:7777/myDocumentDatabase/myCollection/_indexes HTTP/1.1
Content-Type: application/json; charset=utf-8

HTTP/1.1 200 OK

{"_embedded":[{"v":2,"key":{"_id":1},"ns":"dbname.myCollection","_id":"_id_"},{"v":2,"unique":true,"key":{"prop":1},"ns":"dbname.myCollection","sparse":true,"_id":"myindex"}],"_size":2,"_returned":2}

Request

Request URL: GET /<databaseName>/<collectionName>/_indexes

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection

Response

Returns a status code and in case of error, an error message in the response body. If successfull returns also the indexes of the collection.

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 a Document-oriented Document

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

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

{   
    "name":"doc1",
    "rating":"super cool"
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
...
Location: https://localhost:4445/dbname/myCollection/5c35b4cf26b526c21d2a0fdc
...
}

Request

Request URL: POST /doc/<databaseName>/<collectionName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
body Yes Body entity JSON document Document to be inserted.

Response

Returns a status code. If successfull returns also the location of the document, which is its ID.

Common Status Codes Returned

Code Description
201 Created. Document 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.

Create Document-oriented Documents

Creates N documents in a collection in a given document-oriented database.

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

[
    {"name":"doc1","rating":"super cool"},
    {"name":"doc111","rating":"even cooler"}
]
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"inserted":2,"deleted":0,"modified":0,"matched":0,"_links":{"rh:newdoc":[{"href":"/dbname/myCollection/5c35aef295fe130005aa5597"},{"href":"/dbname/myCollection/5c35aef295fe130005aa5598"}]}}

Request

Request URL: POST /doc/<databaseName>/<collectionName>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
body Yes Body entity JSON array of documents Document(s) to be inserted.

Response

Returns a status code, the number of inserted documents and information about them in case of success, including their location, and in case of error, an error message in the response body.

Common Status Codes Returned

Code Description
200 OK. 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/myDocumentDatabase/myCollection/5c35ae1695fe130005aa5594 HTTP/1.1
HTTP/1.1 200 OK

Request

Request URL: DELETE /doc/<databaseName>/<collectionName>/<docId>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
docId Yes Resource String The ID of the document. It is returned in the Location parameter in the creation (or get) 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
204 No Content. The document was succesfully deleted.
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.

Update (patch) 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/myDocumentDatabase/myCollection/5c35ae1695fe130005aa5594  HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "color":"ORANGE"
}
HTTP/1.1 200 OK

Request

Request URL: PATCH /doc/<databaseName>/<collectionName>/<docId>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
docId Yes Resource String The ID of the document. It is returned in the Location parameter in the creation (or get) of the document.
body Yes Body entity JSON object The properties to be updated.

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.

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/myDocumentDatabase/myCollection/5c35ae1695fe130005aa5594  HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "color":"ORANGE"
}
HTTP/1.1 200 OK

Request

Request URL: PUT /doc/<databaseName>/<collectionName>/<docId>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
docId Yes Resource String The ID of the document. It is returned in the Location parameter in the creation (or get) of the document.
body Yes Body entity JSON object The properties to be updated.

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.

Get Document-oriented document

Gets a document of a document-oriented database with a known document identifier.

GET https://api.vfos.com:7777/myDocumentDatabase/myCollection/5af300ef206682b7a2d8da0e HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"_id":{"$oid":"5af300ef206682b7a2d8da0e"},"color":"GREEN","_etag":{"$oid":"5c35cef195fe130005aa55b7"}}

Request

Request URL: GET /doc/<databaseName>/<collectionName>/<docId>

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
docId Yes Resource String The ID of the document. It is returned in the Location parameter in the creation of the document.

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 by properties of a document-oriented database

GET https://api.vfos.com:7777/myDocumentDatabase/myCollection?filter='\{"name":"doc1"\}' HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"_embedded":[
    {"_id":{"$oid":"5c35b4cf26b526c21d2a0fdc"},"name":"doc1","rating":"super cool","_etag":{"$oid":"5c35b4cf95fe130005aa55ad"}},
    {"_id":{"$oid":"5c35b16b26b526c21d2a0f74"},"name":"doc1","rating":"super cool2","_etag":{"$oid":"5c35b16b95fe130005aa55ac"}},
    {"_id":{"$oid":"5c35b16a26b526c21d2a0f72"},"name":"doc1","rating":"super cool3","_etag":{"$oid":"5c35b16a95fe130005aa55ab"}}
    ]
}

Request

Request URL (collections): `GET /doc//?filter=

Transfer Parameters

Name Required Parameter Type Object Type Description
databaseName Yes Resource String Name of the database
collectionName Yes Resource String Name of the collection
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/)]

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.

Time-series Storage

This section describes functionalities regarding time-series data storage. This storage service is best designed to store timestamped values, i.e. sensor data.

It is based on InfluxDB (https://www.influxdata.com) database management system. You can find much more detailed documentantion about the API here:(https://docs.influxdata.com/influxdb/v1.7/tools/api/).

All queries must be URL encoded, so for instance when in examples this is written: http GET https://api.vfos.com:7777/query?q=SHOW DATABASES HTTP/1.1 Content-Type: application/json; charset=utf-8 This is meant: http GET https://api.vfos.com:7777/query?q=SHOW%20DATABASES HTTP/1.1 Content-Type: application/json; charset=utf-8

The former (not encoded) is shown for the shake of clarity.

Create Time-series Database

Creates a new time-series database.

POST https://api.vfos.com:7777/query?q=CREATE DATABASE "myDatabase" HTTP/1.1
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
{"results":[{"statement_id":0}]}

Request

Request URL: POST /query

Transfer Parameters

Name Required Parameter Type Object Type Description
q Yes Query String Command, with the syntax: CREATE DATABASE "databaseName"

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. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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.

POST https://api.vfos.com:7777/query?q=DROP DATABASE "myDatabase" HTTP/1.1
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
{"results":[{"statement_id":0}]}

Request

Request URL: POST /query

Transfer Parameters

Name Required Parameter Type Object Type Description
q Yes Query String Command, with the syntax: DROP DATABASE "databaseName"

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. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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 Databases

Gets the list of databases.

GET https://api.vfos.com:7777/query?q=SHOW DATABASES  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "databases",
                    "columns": [
                        "name"
                    ],
                    "values": [
                        [
                            "_internal"
                        ],
                        [
                            "mydb2"
                        ],
                        [
                            "mydb"
                        ],
                        [
                            "mydb1"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
q Yes Query String Command, with the syntax: SHOW DATABASES

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW 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_load_short"
                        ],
                        [
                            "cpu_temp"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW MEASUREMENTS

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW TAG KEYS ON "myDatabase"  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": [
                        "tagKey"
                    ],
                    "values": [
                        [
                            "host"
                        ],
                        [
                            "region"
                        ]
                    ]
                },
                {
                    "name": "cpu_temp",
                    "columns": [
                        "tagKey"
                    ],
                    "values": [
                        [
                            "host"
                        ],
                        [
                            "region"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW TAG KEYS ON "databaseName"

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW TAG VALUES ON "myDatabase" WITH KEY = "host"  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": [
                        "key",
                        "value"
                    ],
                    "values": [
                        [
                            "host",
                            "server01"
                        ],
                        [
                            "host",
                            "server02"
                        ]
                    ]
                },
                {
                    "name": "cpu_temp",
                    "columns": [
                        "key",
                        "value"
                    ],
                    "values": [
                        [
                            "host",
                            "server02"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW TAG VALUES ON "databaseName" WITH KEY = "keyName"

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW FIELD KEYS ON "myDatabase" FROM "cpu_load_short"  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": [
                        "fieldKey",
                        "fieldType"
                    ],
                    "values": [
                        [
                            "value",
                            "float"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW FIELD KEYS ON "databaseName" FROM "fieldName"

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW 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_load_short,host=server01,region=us-west"
                        ],
                        [
                            "cpu_load_short,host=server02,region=us-west"
                        ],
                        [
                            "cpu_temp,host=server02,region=us-west"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW SERIES

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW 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 /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW RETENTION POLICIES

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=SHOW 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": "mydb2",
                    "columns": [
                        "name",
                        "query"
                    ]
                },
                {
                    "name": "mydb",
                    "columns": [
                        "name",
                        "query"
                    ]
                },
                {
                    "name": "myDatabase",
                    "columns": [
                        "name",
                        "query"
                    ],
                    "values": [
                        [
                            "cq_basic",
                            "CREATE CONTINUOUS QUERY cq_basic ON myDatabase BEGIN SELECT mean(passengers) INTO myDatabase.autogen.average_passengers FROM myDatabase.autogen.bus_data GROUP BY time(1h) END"
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SHOW CONTINUOUS QUERIES

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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: Timestap, value, and optionally tags.

POST https://api.vfos.com:7777/write?db=myDatabase  HTTP/1.1

'cpu_load_med,host=server01,region=us-west value=0.25 1414055562000000000'

HTTP/1.1 204 NO CONTENT
Name Required Parameter Type Object Type Description
databaseName Yes Query String The ID/Name of the database
body Yes Body entity String The data.
precision No Query String (ns,u,ms,s,m,h) Sets the precision for the supplied Unix time values. The default value is nanoseconds.
rp No Query String Retention Policy. Sets the target retention policy for the write. The default value is DEFAULT retention policy if you do not specify a retention policy.

Request

Request URL: POST /write

Response

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

Common Status Codes Returned

Code Description
204 No content. Rows fucessfully inserted
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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.

POST https://api.vfos.com:7777/query?db=myDatabase&q=DELETE FROM "cpu_load_short" HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0
        }
    ]
}

Request

Request URL: POST /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: DELETE FROM "fieldName"

Response

Returns a status code. In case of error it also returns a message in the response body.

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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 points

Delete points from a given time-series database.

POST https://api.vfos.com:7777/query?db=myDatabase&q=DROP SERIES FROM usage WHERE machine='MACHINE1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0
        }
    ]
}

Request

Request URL: POST /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: DELETE FROM "fieldName"

Response

Returns a status code. In case of error it also returns a message in the response body.

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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.

Query Time-series measurement

Queries a measurement of a time-series database

GET https://api.vfos.com:7777/query?db=myDatabase&q=SELECT * FROM "cpu_load_short" where value>1  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": [
                        "time",
                        "host",
                        "region",
                        "value"
                    ],
                    "values": [
                        [
                            "2015-02-16T02:59:23Z",
                            "server01",
                            "us-west",
                            2.65
                        ],
                        [
                            "2015-06-11T20:46:02Z",
                            "server01",
                            "us-west",
                            1.65
                        ],
                        [
                            "2015-06-11T20:46:03Z",
                            "server01",
                            "us-west",
                            1.65
                        ]
                    ]
                }
            ]
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: SELECT * FROM "fieldName" WHERE condition

Response

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

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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 Continuous Query

Creates a new time-series continuous query.

POST https://api.vfos.com:7777/query?db=myDatabase&q=CREATE CONTINUOUS QUERY "cq_basic" ON "myDatabase" BEGIN   SELECT mean("passengers") INTO "average_passengers" FROM "bus_data" GROUP BY time(1h) END  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: CREATE CONTINUOUS QUERY "continousQueryName" ON "databaseName" BEGIN queryDefinition END

Response

Returns a status code. In case of error it returns an error message in the response body.

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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.

POST https://api.vfos.com:7777/query?db=myDatabase&q=DROP CONTINUOUS QUERY "cq_basic" ON "myDatabase"  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: DROP CONTINUOUS QUERY "continousQueryName" ON "databaseName"

Response

Returns a status code. In case of error it returns an error message in the response body.

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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/query?db=myDatabase&q=CREATE RETENTION POLICY "one_day_only" ON "myDatabase" DURATION 1d REPLICATION 1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: CREATE RETENTION POLICY "retentionPolicyName" ON "databaseName" BEGIN policyDefinition END

Response

Returns a status code. In case of error it returns an error message in the response body.

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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 Retention Policy

Drops an existing time-series retention policy.

POST https://api.vfos.com:7777/query?db=myDatabase&q=DROP RETENTION POLICY "one_day_only" ON "myDatabase"  HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "results": [
        {
            "statement_id": 0
        }
    ]
}

Request

Request URL: GET /query

Transfer Parameters

Name Required Parameter Type Object Type Description
db Yes Query String Database name
q Yes Query String Command, with the syntax: DROP RETENTION POLICY "retentionPolicyName" ON "databaseName"

Response

Returns a status code. In case of error it returns an error message in the response body.

Common Status Codes Returned

Code Description
200 Success
400 Bad request. Can occur with a syntactically incorrect query. The returned JSON offers further information.
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.

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:

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&amp; 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, Registry Services and Access Services, with the following base URLs:

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.

Registry: Retrieve all enablers with their sub-components

Retrieve all enablers, associated connection and its available services.

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

[
  {
    "name": "aeon",
    "description": "Cloud Messaging",
    "metadata": {
      "chapter": "Data/Context Management",
      "updated": "2017-06-12"
    },
    "versions": [
      {
        "number": "0.3.0",
        "description": "Beta 3.",
        "protocol": "REST"
      }
    ]
  },
  {
    "name": "orion",
    "description": "Publish/Subscribe Context Broker",
    "metadata": {
      "chapter": "Data/Context Management",
      "updated": "2017-03-09"
    },
    "versions": [
      {
        "number": "1.0",
        "description": "First stable realease.",
        "protocol": "REST"
      }
    ]
  }
]

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

Registry: retrieve a version

Retrieve the connection and its services of a specific enabler.

GET /enablers/orion/versions/1.0.0 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "number": "1.0",
  "enablerName": "orion",
  "description": "First stable realease.",
  "protocol": "NGSIv1",
  "composeUrl": "http://path/to/docker-compose.yml"
}

Request

It contains enablerName and versionNumber, which is a required URL parameter.

Request URL: GET /enablers/:enablerName/versions/:versionNumber

Transfer Parameters

Name Required Parameter Type Object Type Description
enablerName Yes Resource string The name of the enabler
versionNumber Yes Resource string The name of the version

Response

If the response is successful, it returns an http status code and data with enabler's details as well as its version. 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

Registry: retrieve a service

Retrieve a specific service of one enabler.

GET /enablers/orion/versions/1.0.0/services/getTypeInfo HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "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"
  }
}

Request

Request URL: GET /enablers/<enablerName>/versions/<versionNumber>/services/<serviceName>

Transfer Parameters

Name Required Parameter Type Object Type Description
enablerName Yes Resource string The name of a specific enabler
versionNumber Yes Resource string The name of the version
serviceName Yes Resource string The name of a specific service

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

Registry: create an instance

Create a specific instance of the version of the enabler.

GET /enablers/orion/versions/1.0/instances HTTP/1.1
HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8

Request

Request URL: POST /enablers/<enablerName>/versions/<versionNumber>/instances

Transfer Parameters

Name Required Parameter Type Object Type Description
enablerName Yes Resource string The name of a specific enabler
versionNumber Yes Resource string The name of the version

Data Parameters

Name Required Parameter Type Object Type Description
name Yes Body string The name of a specific instance
description Yes Body string Description of the instance
url No Body string Url of the instance
port No Body string Port of the instance
access Yes Body boolean Define if the instance is public ou private
autoInstall Yes Body boolean Instance is automatically installed
status Yes Body enum Status of the instance. It can be Running, Error or installing

Response

If the response is successful, it returns an http status code.

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

Registry: retrieve an instance

Retrieve a specific instance of one enabler.

GET /enablers/orion/versions/1.0/instances/gris HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "name": "gris",
  "description": "Orion running on GRIS servers.",
  "url": "http://gris.uninova.pt",
  "port": 5911,
  "access": "Private",
  "status": "Running",
  "autoInstall": false
}

Request

Request URL: GET /enablers/<enablerName>/versions/<versionNumber>/instances/<instanceName>

Transfer Parameters

Name Required Parameter Type Object Type Description
enablerName Yes Resource string The name of a specific enabler
versionNumber Yes Resource string The name of the version
instanceName Yes Resource string The name of a specific instance

Response

If the response is successful, it returns an http status code and data with instance'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/orion/3.0/gris/getEntity HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "vapp": "37f805f710547643b529f2ca797fab6e",
  "bodyParams":{
    "type":"channel"
  }
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "correlator":"182fdb0c-9863-11e7-946b-0242ac110003",
  "entity":{
    "id":"LED001",
    "type":"LED",
    "switch":{
      "type":"string",
      "value":"0034223456789",
      "metadata":{

      }
    }
  }
}

Request

Request URL: POST /accessfunctionality/<enablerName>/<versionNumber>/<instanceName>/<serviceName>

Transfer Parameters

Name Required Parameter Type Object Type Description
enablerName Yes Resource string Enabler Name
versionNumber Yes Resource string Version Number
instanceName Yes Resource string Instance 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

This API describes the main operations with regard to authentication. 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. 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:

In order to administer the identity service through the API is necessary to obtain a token, the following methods permit to obtain a token:

Create token with Password method

Creation of a token based on Username/Password credentials http POST /v1/auth/tokens Content-Type:application/json { "name": "[email protected]", "password": "passw0rd" }

HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
X-Subject-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Length:74
ETag:W/"4a-jYFzvNRMQcIZ2P+p5EfmbN+VHcw"
Date:Mon, 19 Mar 2018 15:05:35 GMT
Connection:keep-alive

{
  "token": {
    "methods": [
      "password"
    ],
    "expires_at": "2018-03-20T15:05:35.697Z"
  }
}
Request

Request URL: POST /v1/auth/tokens

Transfer Parameters
Name Required Parameter Type Object Type Description
Content-Type Yes Header String Formato of the request: application/json
name Yes Body String Username
password Yes Body String Password

Create token with Token method

Creation of a token based on existing token http POST /v1/auth/tokens Content-Type:application/json { "token": "token_id" }

HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
X-Subject-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Length:74
ETag:W/"4a-jYFzvNRMQcIZ2P+p5EfmbN+VHcw"
Date:Mon, 19 Mar 2018 15:05:35 GMT
Connection:keep-alive
{
  "token": {
    "methods": [
      "password"
    ],
    "expires_at": "2018-03-20T15:05:35.697Z"
  }
}

X-Subject-Token is used in all subsequent requests to obtain access.

Request

Request URL: POST /v1/auth/tokens

Transfer Parameters
Name Required Parameter Type Object Type Description
Content-Type Yes Header String Format of the request: application/json
token Yes Body String Existing token

Get token info

GET /v1/auth/tokens
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
X-Subject-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:278
ETag:W/"116-JwJR8Y5eFV2SDon0j1GX5yWyNx4"
Date:Tue, 20 Mar 2018 15:23:21 GMT
Connection:keep-alive
{
  "access_token": "f0a0a067-6341-4943-8225-45f794b3d94b",
  "expires": "2019-03-21T15:22:33.000Z",
  "valid": true,
  "User": {
    "id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
    "username": "mike_new",
    "email": "[email protected]",
    "date_password": "2019-03-20T12:12:09.000Z",
    "enabled": true,
    "admin": false
  }
}
Request

Request URL: GET /v1/auth/tokens

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token, is the same of the subject-token in the case the user is making a query about itself.
X-Subject-Token Yes Header String Token corresponding of the logged user

Delete token

DELETE /v1/auth/tokens
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
X-Subject-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Content-Type:application/json
Request

Request URL: DELETE /v1/auth/tokens

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token, is the same of the subject-token in the case the user is making a query about itself.
X-Subject-Token Yes Header String Token corresponding of the logged user

Application

All applications that need to be protected are required to be registered before any client can consume services.

The following methods are available: * Create an Application * Read Application details * Update an Application * Delete an Application * List Applications

Create an Application

POST /v1/applications
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{
  "application": {
    "name": "Test_application 1",
    "description": "description",
    "redirect_uri": "http://localhost/login",
    "url": "http://localhost",
    "grant_type": [
      "authorization_code",
      "implicit",
      "password"
    ],
    "token_types": [
        "jwt",
        "permanent"
    ]
  }
}
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:329
ETag:W/"149-yQORsIAntQ0YHR5uCyLZhk7jTkg"
Date:Tue, 20 Mar 2018 10:16:13 GMT
Connection:keep-alive
{
  "application": {
    "id": "fd7fe349-f7da-4c27-b404-74da17641025",
    "secret": "9dc463cf-8318-4f65-bc02-778424fdfd77",
    "image": "default",
    "name": "Test_application 1",
    "description": "description",
    "redirect_uri": "http://localhost/login",
    "url": "http://localhost",
    "grant_type": "password,authorization_code,implicit",
    "token_types": "jwt,permanent",
    "jwt_secret": "3f1164da20d50c62",
    "response_type": "code,token"
  }
}
Request

Request URL: POST /v1/applications

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
name Yes Header String Application name
description Yes Header String Application description
redirect_uri Yes Header String Logon url
url Yes Header String Application url
grant_type Yes Header Array[String] Grant types to be supported
token_types Yes Header Array[String] Token types to be supported

Read Application details

GET /v1/applications/0fbfa58c-e5b6-41c3-b748-ab29f1567a9c
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:407
ETag:W/"197-biN1lSH/UM4L+dEtIoLYyOGteWE"
Date:Tue, 20 Mar 2018 10:25:33 GMT
Connection:keep-alive
{
  "application": {
    "id": "0fbfa58c-e5b6-41c3-b748-ab29f1567a9c",
    "name": "Test_application 2",
    "description": "Description",
    "secret": "61f5def7-bcf9-45b1-9c69-d0887e403737",
    "url": "http://localhost",
    "redirect_uri": "http://localhost/login",
    "image": "default",
    "grant_type": "client_credentials,password,implicit,authorization_code,refresh_token",
    "response_type": "code,token",
    "token_types": "bearer,jwt,permanent",
    "jwt_secret": "3f1164da20d50c62",
    "client_type": null,
    "scope": null,
    "extra": null
  }
}
Request

Request URL: GET /v1/applications/application_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Update an Application

PATCH /v1/applications/0fbfa58c-e5b6-41c3-b748-ab29f1567a9c
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{
    "application": {
        "name": "new name",
        "description": "new description",
        "redirect_uri": "new redirect uri",
        "token_types": ["permanent"]
        "grant_type": [
            "authorization_code",
            "password"
        ]
    }
}
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:170
ETag:W/"aa-XCFRn1K54wlgPzun8PluFjYwCO0"
Date:Tue, 20 Mar 2018 10:29:04 GMT
Connection:keep-alive
{
  "values_updated": {
    "name": "new name",
    "description": "new description",
    "redirect_uri": "new redirect uri",
    "grant_type": "password,authorization_code",
    "token_types": "permanent",
    "jwt_secret": null,
    "response_type": "code"
  }
}
Request

Request URL: PATCH /v1/applications/application_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
name Yes Header String New application name
description Yes Header String New application description
redirect_uri Yes Header String New logon url
grant_type Yes Header Array[String] New grant types to be supported
token_types Yes Header Array[String] New token types to be supported

Delete an Application

DELETE /v1/applications/0fbfa58c-e5b6-41c3-b748-ab29f1567a9c
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
HTTP/1.1 204 OK
Content-Type:application/json
Request

Request URL: DELETE /v1/applications/application_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token

List Applications

GET /v1/applications
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:303
ETag:W/"12f-64q7xcRDNfw7c2xrc1r2S5EFS6k"
Date:Tue, 20 Mar 2018 10:14:30 GMT
Connection:keep-alive
{
  "applications": [
    {
      "id": "0fbfa58c-e5b6-41c3-b748-ab29f1567a9c",
      "name": "Test_application 2",
      "description": "Description",
      "image": "default",
      "url": "http://localhost",
      "redirect_uri": "http://localhost/login",
      "grant_type": "client_credentials,password,implicit,authorization_code,refresh_token",
      "response_type": "code,token",
      "token_types": "bearer,jwt,permanent",
      "client_type": null
    },
    {
      "id": "fd7fe349-f7da-4c27-b404-74da17641025",
      "name": "Test_application 1",
      "description": "description",
      "image": "default",
      "url": "http://localhost",
      "redirect_uri": "http://localhost/login",
      "grant_type": "password,authorization_code,implicit",
      "response_type": "code,token",
      "token_types": "bearer",
      "client_type": null
    }
  ]
}
Request

Request URL: GET /v1/applications

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token

Users

This API describes the main operations for managing users: * Create User * Read info about a User * Update a User * Delete a User * List Users

Create User

POST /v1/users
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{
    "user": {
        "username": "alice",
        "email": "[email protected]",
        "password": "passw0rd"
    }
}
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:205
ETag:W/"cd-hbCwPDJrO5NvpsY2pqY6Qhlf/do"
Date:Tue, 20 Mar 2018 09:31:07 GMT
Connection:keep-alive
{
  "user": {
    "id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
    "image": "default",
    "gravatar": false,
    "enabled": true,
    "admin": false,
    "username": "alice",
    "email": "[email protected]",
    "date_password": "2018-03-20T09:31:07.104Z"
  }
}
Request

Request URL: POST /v1/users

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
username Yes Body String Username
password Yes Body String Password

Read info about a User

GET /v1/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:239
ETag:W/"ef-346BFly5PUZzqso7/DhcynciNPs"
Date:Tue, 20 Mar 2018 10:34:20 GMT
Connection:keep-alive
{
  "user": {
    "id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
    "username": "alice",
    "email": "[email protected]",
    "enabled": true,
    "admin": false,
    "image": "default",
    "gravatar": false,
    "date_password": "2018-03-20T09:31:07.000Z",
    "description": null,
    "website": null
  }
}
Request

Request URL: GET /v1/users/user_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
user_id Yes URI String Username Id

Update a User

PATCH /v1/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{ 
    "user": {
      "username": "new_alice",
      "password": "passw0rd_new"
    }
}
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:72
ETag:W/"48-NygV9BIfH5juflD+icW6fPFuBkA"
Date:Tue, 20 Mar 2018 10:38:59 GMT
Connection:keep-alive
{
  "values_updated": {
    "username": "new_alice",
    "email": "[email protected]"
  }
}
Request

Request URL: PATCH /v1/users/user_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
user_id Yes URI String Username Id
username Yes Body String Username Id
password Yes Body String User Password

Delete a User

DELETE /v1/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Content-Type:application/json
Request

Request URL: PATCH /v1/users/user_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
user_id Yes URI String Username Id

List Users

GET /v1/users
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:378
ETag:W/"17a-/TnzfhPjjd4IG4D1u38zPZiSIL0"
Date:Tue, 20 Mar 2018 10:08:27 GMT
Connection:keep-alive
{
  "users": [
    {
      "id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
      "username": "alice",
      "email": "[email protected]",
      "enabled": true,
      "gravatar": false,
      "date_password": "2018-03-20T09:31:07.000Z",
      "description": null,
      "website": null
    },
    {
      "id": "admin",
      "username": "admin",
      "email": "[email protected]",
      "enabled": true,
      "gravatar": false,
      "date_password": "2018-03-20T08:40:14.000Z",
      "description": null,
      "website": null
    }
  ]
}
Request

Request URL: GET /v1/users

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token

Organizations

This API describes the main operations for managing organizations which involves the following operations: * Create an Organization * Read info about an Organization * Update an Organization * Delete an Organization * List Organizations

Create an organization

POST /v1/organizations
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{
    "organization": {
        "name": "Test organization",
        "description": "description"
    }
} 
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:135
ETag:W/"87-mQPZWVCWNw1jTeBUp2u6DfQUBXg"
Date:Tue, 20 Mar 2018 10:41:14 GMT
Connection:keep-alive
{
  "organization": {
    "id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd",
    "image": "default",
    "name": "Test organization",
    "description": "description"
  }
}
Request

Request URL: POST /v1/organizations

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
name Yes Body String Name of the organization
description Body Header String Description of the organization

Read info about an organization

GET /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:150
ETag:W/"96-Gd8UZNti5b/l9AK7zLVUgoPzoSg"
Date:Tue, 20 Mar 2018 10:46:47 GMT
Connection:keep-alive
{
  "organization": {
    "id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd",
    "name": "Test organization",
    "description": "description",
    "website": null,
    "image": "default"
  }
}
Request

Request URL: GET /v1/organizations/organization_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
organization_id Yes Body String Id of the organization

Update an organization

PATCH /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{
  "organization": {
    "description": "new description",
    "website": "http://test.com"
  }
}
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:80
ETag:W/"50-SLhFvXhKe+sDolh13Q+2u5eotYw"
Date:Tue, 20 Mar 2018 10:48:45 GMT
Connection:keep-alive
{
  "values_updated": {
    "description": "new description",
    "website": "http://test.com"
  }
}
Request

Request URL: PATCH /v1/organizations/organization_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
organization_id Yes Body String Id of the organization

Delete an organization

DELETE /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json
Request

Request URL: DELETE /v1/organizations/organization_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
organization_id Yes Body String Id of the organization

List Organizations

GET /v1/organizations/
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
Content-Length:355
ETag:W/"163-0eDqBVBTEbKRQmAm6AtzDLXVigI"
Date:Tue, 20 Mar 2018 10:45:36 GMT
Connection:keep-alive
{
  "organizations": [
    {
      "role": "owner",
      "Organization": {
        "id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
        "name": "Test organization 2",
        "description": "description 2",
        "image": "default",
        "website": null
      }
    },
    {
      "role": "owner",
      "Organization": {
        "id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd",
        "name": "Test organization",
        "description": "description",
        "image": "default",
        "website": null
      }
    }
  ]
}
Request

Request URL: GET /v1/organizations/

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token

Permissions

Create a permission

POST /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/permissions
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
{
  "permission": {
    "name": "permission 1",
    "action": "GET",
    "resource": "login"
  }
} 
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:193
ETag:W/"c1-WkjxOsda9h0YVjVe6wfJ3/BB5/E"
Date:Tue, 20 Mar 2018 11:34:41 GMT
Connection:keep-alive
{
  "permission": {
    "id": "15ca810b-27d1-44a1-8491-a3fb4b6bc6f3",
    "is_internal": false,
    "name": "permission 1",
    "action": "GET",
    "resource": "login",
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025"
  }
}
Request

Request URL: POST /v1/applications/application_id/permissions

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
name Yes Body String Name of the permission
action Body Header String HTTP Verb
resource Body Header String HTTP Resource

Read Permission details

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/permissions/15ca810b-27d1-44a1-8491-a3fb4b6bc6f3
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:223
ETag:W/"df-8dskjqxwg2z2vTSGP00GOfWr7ak"
Date:Tue, 20 Mar 2018 11:42:26 GMT
Connection:keep-alive
{
  "permission": {
    "id": "15ca810b-27d1-44a1-8491-a3fb4b6bc6f3",
    "name": "permission 1",
    "description": null,
    "is_internal": false,
    "action": "GET",
    "resource": "login",
    "xml": null,
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025"
  }
}
Request

Request URL: GET /v1/applications/application_id/permissions/permission_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes Body String Application Id
permission_id Body Header String Permission Id

Update a Permission

PATCH /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/permissions/15ca810b-27d1-44a1-8491-a3fb4b6bc6f3
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
{
  "permission": {
    "name": "new name permission",
    "description": "new description permission",
    "xml": "jambuno"
  }
}
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:109
ETag:W/"6d-DcRDt9VL8q5NI3uqNXNrX+2Kq0U"
Date:Tue, 20 Mar 2018 11:45:49 GMT
Connection:keep-alive
{
  "values_updated": {
    "name": "new name permission",
    "description": "new description permission",
    "xml": "xml rule"
  }
}
Request

Request URL: PATCH /v1/applications/application_id/permissions/permission_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
name Yes Body String Permission name
description Body Header String Permission description
xml Body Header String Tag

Delete a Permission

DELETE /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/permissions/15ca810b-27d1-44a1-8491-a3fb4b6bc6f3
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Content-Type:application/json
Request

Request URL: DELETE /v1/applications/application_id/permissions/permission_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token

List Permissions

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/permissions
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:816
ETag:W/"330-B4K+xvKY9Z0W5Qhy4XfXIxsJnwU"
Date:Tue, 20 Mar 2018 11:41:23 GMT
Connection:keep-alive
{
  "permissions": [
    {
      "id": "6",
      "name": "Get and assign only public owned roles",
      "description": null,
      "action": null,
      "resource": null,
      "xml": null
    },
    {
      "id": "5",
      "name": "Get and assign all public application roles",
      "description": null,
      "action": null,
      "resource": null,
      "xml": null
    }
  ]
}
Request

Request URL: GET /v1/applications/application_id/permissions

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token

Roles

Create a Role

POST /v1/applications//roles
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
{
  "role": {
    "name": "role 1"
  }
}
HTTP/1.1 201 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:147
ETag:W/"93-gmWMlkuHssLlhgsbkRsYJjI1ZpE"
Date:Tue, 20 Mar 2018 10:56:16 GMT
Connection:keep-alive
{
  "role": {
    "id": "33fd15c0-e919-47b0-9e05-5f47999f6d91",
    "is_internal": false,
    "name": "role 1",
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025"
  }
}
Request

Request URL: POST /v1/applications/application_id/roles

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
name Yes Header String Authorization token

Read Role details

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles/1
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:147
ETag:W/"93-jWdaZFK7V/AOFD7WOIM0aZePmqg"
Date:Tue, 20 Mar 2018 11:21:19 GMT
Connection:keep-alive
{
  "role": {
    "id": "33fd15c0-e919-47b0-9e05-5f47999f6d91",
    "name": "role 1",
    "is_internal": false,
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025"
  }
}
Request

Request URL: GET /v1/applications/application_id/roles/role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
role_id Yes URI String Role Id

Update a Role

PATCH /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles/1
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
{
  "role": {
    "name": "test_role_new",
    "application_id": "2222"
  }
}
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:43
ETag:W/"2b-pM4WlfxN6zpTuxeiYjs7ZBMAimM"
Date:Tue, 20 Mar 2018 11:24:07 GMT
Connection:keep-alive
{
  "values_updated": {
    "name": "new role name"
  }
}
Request

Request URL: PATCH /v1/applications/application_id/roles/role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
role_id Yes URI String Role Id
name Yes Body String Name of the role

Delete a Role

DELETE /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles/1
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Content-Type:application/json
Request

Request URL: DELETE /v1/applications/application_id/roles/role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
role_id Yes URI String Role Id

List Roles

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json
{
  "roles": [
    {
      "id": "purchaser",
      "name": "Purchaser"
    },
    {
      "id": "provider",
      "name": "Provider"
    },
    {
      "id": "ee2ec16f-694b-447f-b61a-e293b6fe5f7b",
      "name": "role 2"
    },
    {
      "id": "33fd15c0-e919-47b0-9e05-5f47999f6d91",
      "name": "role 1"
    }
  ]
}
Request

Request URL: GET /v1/applications/application_id/roles

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

PEP Proxies

Create a PEP Proxy

POST /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/pep_proxies
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:129
ETag:W/"81-pV8lmjYRuvS5Nc/SlKF+oCjMPlo"
Date:Tue, 20 Mar 2018 11:56:18 GMT
Connection:keep-alive
{
  "pep_proxy": {
    "id": "pep_proxy_2d19d297-e555-4e3a-a18d-22deda37036a",
    "password": "pep_proxy_950468f7-4198-42e1-8f41-4b1f8c5bc1f2"
  }
}
Request

Request URL: POST /v1/applications/application_id/pep_proxies

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Info a PEP Proxy

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/pep_proxies
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:126
ETag:W/"7e-WPTcZsaLk+L8CA5OdIqizFHVrPw"
Date:Tue, 20 Mar 2018 11:57:37 GMT
Connection:keep-alive
{
  "pep_proxy": {
    "id": "pep_proxy_2d19d297-e555-4e3a-a18d-22deda37036a",
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025"
  }
}
Request

Request URL: GET /v1/applications/application_id/pep_proxies

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Reset Password of PEP Proxy

PATCH /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/pep_proxies
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:65
ETag:W/"41-U+BN5OW2bt+63vlUf0I9i/DAZ6M"
Date:Tue, 20 Mar 2018 11:58:45 GMT
Connection:keep-alive
{
  "new_password": "pep_proxy_3b2c8791-71b9-444a-b8c7-00d37cf35149"
}
Request

Request URL: PATCH /v1/applications/application_id/pep_proxies

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Delete PEP Proxy

DELETE /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/pep_proxies
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Content-Type:application/json
Request

Request URL: DELETE /v1/applications/application_id/pep_proxies

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Management: Permissions & Roles

Assign a permission to a role

POST /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles/1/permissions/2
Content-Type:application/json
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
X-Powered-By:Express
Content-Type:application/json; charset=utf-8
Content-Length:102
ETag:W/"66-G5t4RaonrlcbX68lBuXLPzS+Glc"
Date:Tue, 20 Mar 2018 12:18:41 GMT
Connection:keep-alive
{
  "role_permission_assignments": {
    "role_id": "33fd15c0-e919-47b0-9e05-5f47999f6d91",
    "permission_id": "4"
  }
}
Request

Request URL: POST /v1/applications/application_id/roles/role_id/permissions/permissions_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
role_id Yes URI String Role Id
permissions_id Yes URI String Permission Id

Remove a permission from a role

DELETE /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles/1/permissions/2
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
X-Powered-By:Express
Content-Type:application/json
Request

Request URL: DELETE /v1/applications/application_id/roles/role_id/permissions/permissions_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
role_id Yes URI String Role Id
permissions_id Yes URI String Permission Id

List permissions associated to a Role

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/roles/1/permissions
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:475
ETag:W/"1db-abmPwZLikwp2EbYVmU/UKdHtbGE"
Date:Tue, 20 Mar 2018 12:15:29 GMT
Connection:keep-alive
{
  "role_permission_assignments": [
    {
      "id": "15ca810b-27d1-44a1-8491-a3fb4b6bc6f3",
      "is_internal": false,
      "name": "new name permission",
      "description": "new description permission",
      "action": null,
      "resource": null,
      "xml": "xml rule"
    },
    {
      "id": "3",
      "is_internal": true,
      "name": "Manage roles",
      "description": null,
      "action": null,
      "resource": null,
      "xml": null
    },
    {
      "id": "1",
      "is_internal": true,
      "name": "Get and assign all internal application roles",
      "description": null,
      "action": null,
      "resource": null,
      "xml": null
    }
  ]
}
Request

Request URL: GET /v1/applications/application_id/roles/role_id/permissions

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
role_id Yes URI String Role Id

Management: Organizations & Users

Add member to Organization (Create relationship)

POST /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb/organization_roles/2
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json; charset=utf-8
Content-Length:125
ETag:W/"7d-lt1JE+QQNKxkfaswZ+ZRWXj2vdk"
Date:Tue, 20 Mar 2018 12:55:58 GMT
Connection:keep-alive
{
  "user_organization_assignments": {
    "role": "owner",
    "user_id": "admin",
    "organization_id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd"
  }
}
Request

Request URL: POST /v1/organizations/organization_id/users/user_id/organization_roles/organization_role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
organization_id Yes URI String Organization Id
user_id Yes URI String Role Id
organization_role_id Yes URI String Organization Role Id

Info of user organization relationship

GET /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb/organization_roles
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
Content-Type:application/json; charset=utf-8
Content-Length:114
ETag:W/"72-/fZonAf/VJOEZ94bshoBRSVQzmE"
Date:Tue, 20 Mar 2018 12:51:28 GMT
Connection:keep-alive
{
  "organization_user": {
    "user_id": "admin",
    "organization_id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd",
    "role": "member"
  }
}
Request

Request URL: GET /v1/organizations/organization_id/users/user_id/organization_roles

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
organization_id Yes URI String Organization Id
user_id Yes URI String Role Id
organization_id Yes URI String Organization Role Id

Remove member to Organization (Delete relationship)

DELETE /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb/organization_roles/1
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Content-Type:application/json

List members of an Organization

GET /v1/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd/users
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
Content-Type:application/json; charset=utf-8
Content-Length:240
ETag:W/"f0-3G8Dv2NqT3KMGuO+jRta+nJMnJk"
Date:Tue, 20 Mar 2018 12:47:26 GMT
Connection:keep-alive
{
  "organization_users": [
    {
      "user_id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
      "organization_id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd",
      "role": "owner"
    },
    {
      "user_id": "admin",
      "organization_id": "3e20722f-d420-422d-89ba-3ae87bc1c0cd",
      "role": "member"
    }
  ]
}
Request

Request URL: GET /v1/organizations/organization_id/users

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
organization_id Yes URI String Organization Id

Management: Roles & Users & Applications

Assign a role to a user

POST /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb/roles/33fd15c0-e919-47b0-9e05-5f47999f6d91
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
Content-Type:application/json
HTTP/1.1 201 OK
X-Powered-By:Express
Content-Type:application/json; charset=utf-8
Content-Length:155
ETag:W/"9b-PTfLJchMB1s6mXINkQh6OJQnSgY"
Date:Tue, 20 Mar 2018 12:31:58 GMT
Connection:keep-alive
{
  "role_user_assignments": {
    "role_id": "purchaser",
    "user_id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025"
  }
}
Request

Request URL: POST /v1/applications/application_id/users/user_id/roles/role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
user_id Yes URI String User Id
role_id Yes URI String Role Id

List users role assignments

GET /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb/roles
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:199
ETag:W/"c7-kciYHLq/V20GkqNyzgr7HDzrWI4"
Date:Tue, 20 Mar 2018 12:29:34 GMT
Connection:keep-alive
{
  "role_user_assignments": [
    {
      "user_id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
      "role_id": "provider"
    },
    {
      "user_id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
      "role_id": "ee2ec16f-694b-447f-b61a-e293b6fe5f7b"
    }
  ]
}
Request

Request URL: GET /v1/applications/application_id/users/user_id/roles

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
user_id Yes URI String User Id

List users in an application

GEThttp://keyrock/v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/users
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:310
ETag:W/"136-lW/H57r3jyK+ObyFOlWMB5tMuNU"
Date:Tue, 20 Mar 2018 12:27:09 GMT
Connection:keep-alive
{
  "role_user_assignments": [
    {
      "user_id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
      "role_id": "provider"
    },
    {
      "user_id": "admin",
      "role_id": "purchaser"
    },
    {
      "user_id": "2d6f5391-6130-48d8-a9d0-01f20699a7eb",
      "role_id": "ee2ec16f-694b-447f-b61a-e293b6fe5f7b"
    },
    {
      "user_id": "admin",
      "role_id": "ee2ec16f-694b-447f-b61a-e293b6fe5f7b"
    }
  ]
}
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Remove a role assignment from a user

DELETE /v1/applications/fd7fe349-f7da-4c27-b404-74da17641025/users/2d6f5391-6130-48d8-a9d0-01f20699a7eb/roles/33fd15c0-e919-47b0-9e05-5f47999f6d91
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Request

Request URL: DELETE /v1/applications/application_id/users/user_id/roles/role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
user_id Yes URI String User Id
role_id Yes URI String Role Id

Management: Roles & Organizations & Applications

Assign a role to an organization

POST /v1/applications/0fbfa58c-e5b6-41c3-b748-ab29f1567a9c/organizations/3e20722f-d420-422d-89ba-3ae87bc1c0cd/roles/33fd15c0-e919-47b0-9e05-5f47999f6d91/organization_roles/3e20722f-d420-422d-89ba-3ae87bc1c0cd
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 201 OK
X-Powered-By:Express
Content-Type:application/json; charset=utf-8
Content-Length:198
ETag:W/"c6-6eTVB6vyiwH6XKLZ3pLYYDXFMm4"
Date:Tue, 20 Mar 2018 12:41:47 GMT
Connection:keep-alive
{
  "role_organization_assignments": {
    "role_id": "provider",
    "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
    "oauth_client_id": "fd7fe349-f7da-4c27-b404-74da17641025",
    "role_organization": "owner"
  }
}
Request

Request URL: POST /v1/applications/application_id/organizations/organization_id/roles/role_id/organization_roles/organization_role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
organization_id Yes URI String Organization Id
role_id Yes URI String Role Id
organization_role_id Yes URI String Organization Id

List organizations role assignments

GET /v1/applications/3e20722f-d420-422d-89ba-3ae87bc1c0cd/organizations/33cf4d3c-8dfb-4bed-bf37-7647f45528ec/roles
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:332
ETag:W/"14c-Itun6PzsweI15qednKd5+tG7Oh0"
Date:Tue, 20 Mar 2018 12:39:20 GMT
Connection:keep-alive
{
  "role_organization_assignments": [
    {
      "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
      "role_id": "purchaser"
    },
    {
      "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
      "role_id": "ee2ec16f-694b-447f-b61a-e293b6fe5f7b"
    },
    {
      "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
      "role_id": "33fd15c0-e919-47b0-9e05-5f47999f6d91"
    }
  ]
}
Request

Request URL: GET /v1/applications/application_id/organizations/organization_id/roles

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
organization_id Yes URI String Organization Id

List organizations in an application

GET /v1/applications/3e20722f-d420-422d-89ba-3ae87bc1c0cd/organizations
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 200 OK
Content-Type:application/json,application/json; charset=utf-8
X-Powered-By:Express
Content-Length:798
ETag:W/"31e-yAFZkeaD7GA4Xo4F6dAyMc/FISM"
Date:Tue, 20 Mar 2018 12:37:51 GMT
Connection:keep-alive
{
  "role_organization_assignments": [
    {
      "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
      "role_organization": "owner",
      "role_id": "purchaser"
    },
    {
      "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
      "role_organization": "owner",
      "role_id": "ee2ec16f-694b-447f-b61a-e293b6fe5f7b"
    },
    {
      "organization_id": "33cf4d3c-8dfb-4bed-bf37-7647f45528ec",
      "role_organization": "member",
      "role_id": "33fd15c0-e919-47b0-9e05-5f47999f6d91"
    }
  ]
}
Request

Request URL: GET /v1/applications/application_id/organizations

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id

Remove a role assignment from an organization

DELETE /v1/applications/application_id/organizations/33cf4d3c-8dfb-4bed-bf37-7647f45528ec/roles/ee2ec16f-694b-447f-b61a-e293b6fe5f7b/organization_roles/33fd15c0-e919-47b0-9e05-5f47999f6d91
X-Auth-Token:04c5b070-4292-4b3f-911b-36a103f3ac3f
HTTP/1.1 204 OK
Request

Request URL: DELETE /v1/applications/application_id/organizations/organization_id/roles/role_id/organization_roles/organization_role_id

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
application_id Yes URI String Application Id
organization_id Yes URI String Organization Id
role_id Yes URI String Role Id
organization_role_id Yes URI String Organization Id

Security - Policy Decision Point

This section covers the main functionalities of the advanced authorization service by defining a RESTful API of an Authorization Policy Decision Point (PDP) compliant with the OASIS XACML standard. It defines RESTful interfaces for: * Managing policies based on XACML-compliant; * Requesting authorization decisions in a XACML-compliant format; * Managing multiple authorization domains, in order to provide multi-tenancy. On the other hand the Policy Administration Point (PAP) allows to administer different domains and policies.

Terminology

Policy and PolicySet

A Policy is a set of Rules, and a PolicySet is a set of Policy elements. A Rule consists of a condition on the access request attributes, and a decision – Permit or Deny - to apply if the condition is true.

Domain

The API is designed to be multi-tenant, i.e. it allows users or organizations to work on authorization policies in complete isolation 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.

This section covers the main functionalities of the authorization service:

Domains

The list of operations supported are the following: * Add Domain * Get Domains * Delete Domain * Update Domain properties * Get Domain sub-resources

Add Domain

POST /domains
Content-Type:application/xml
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" externalId="my.test.domain">
    <description>This is a test domain.</description>
</domainProperties>
HTTP/1.1 200 OK
Content-Type:application/xml
<link xmlns="http://www.w3.org/2005/Atom" rel="item" href="1234ABCD" title="1234ABCD"/>
Request

Request URL: POST /domains

Transfer Parameters
Name Required Parameter Type Object Type Description
xacml domain Yes Body String XACML 3.0 Domain

Get Domains

GET /domains?externalId=my.test.domain
HTTP/1.1 200 OK
Content-Type:application/xml
<resources xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" xmlns:atom="http://www.w3.org/2005/Atom"> 
    <atom:link rel="item" href="1234ABCD" title="1234ABCD"/>
</resources>
Request

Request URL: GET /domains?externalId=external_id

Transfer Parameters
Name Required Parameter Type Object Type Description
externalId Yes URI String XACML 3.0 Domain External Id

Delete Domain

DELETE /domains/1234ABCD
HTTP/1.1 200 OK
Content-Type:application/xml
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" 
    externalId="my.test.domain">
    <description>This is a test domain.</description>
</domainProperties>

Get Domain sub-resources

GET /domains/1234ABCD
HTTP/1.1 200 OK
Content-Type:application/xml
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" externalId="my.test.domain">
    <description>This is a test domain.</description>
</domainProperties>
Request

Request URL: GET /domains/domainId

Transfer Parameters
Name Required Parameter Type Object Type Description
domainId Yes URI String XACML 3.0 Domain Id

Get Domain properties

GET /domains/1234ABCD/properties
HTTP/1.1 200 OK
Content-Type:application/xml
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" 
    externalId="my.test.domain0">
    <description>This is a test domain and I want to use it.</description>
</domainProperties>
Request

Request URL: GET /domains/domainId/properties

Transfer Parameters
Name Required Parameter Type Object Type Description
domainId Yes URI String XACML 3.0 Domain Id

Update Domain properties

PUT /domains/1234ABCD/properties
Content-Type:application/xml
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" 
    externalId="my.test.domain0">
    <description>This is a test domain and I want to use it.</description>
</domainProperties>
HTTP/1.1 200 OK
Content-Type:application/xml
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" 
    externalId="my.test.domain0">
    <description>This is a test domain and I want to use it.</description>
</domainProperties>
Request

Request URL: PUT /domains/domainId/properties

Transfer Parameters
Name Required Parameter Type Object Type Description
domainId Yes URI String XACML 3.0 Domain Id

Policy Administration Point

The list of operations supported are the following: * Add/Update a policy * Get Policies * Get Policy * Get Policy version * Delete Policy * Delete Policy version

Add/Update policy

POST /domains/factory1/pap/policies 
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.

Get Policies

Generates policies and policy versions

GET /domains/factory1/pap/policies 
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 Policy ID.

Delete Policy

Removes policies and policy versions

DELETE /domains/factory11/pap/policies/pol11
HTTP/1.1 200 OK
Content-Type:application/xml
<resources xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5" xmlns:atom="http://www.w3.org/2005/Atom"> 
    <atom:link rel="item" href="1.0" title="1.0"/>
    <atom:link rel="item" href="1.1" title="1.1"/>
    <atom:link rel="item" href="2.0" title="2.0"/>
    ...
</resources>

Request URL: DELETE /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 Policy ID.

Get Policy version

GET /domains/factory1/pap/policies/1.0 
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>/version

Transfer Parameters
Name Required Parameter Type Object Type Description
Domain_id Yes Path String Domain ID.
Policy_id Yes Path String Policy ID.

Delete Policy version

Removes policies and policy versions

DELETE /domains/factory11/pap/policies/pol11/1.0
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: DELETE /domains/<domainId>/pap/policies/<policyId>/Version

Transfer Parameters
Name Required Parameter Type Object Type Description
policyId Yes Path String Policy ID.
Version Yes Path String Policy Version.

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.

Policy Decision Point

The list of operations supported are the following: * Request authorization decision

Request authorization decision

POST /domains/iMnxv7sDEeWFwqVFFMDLTQ/pdp
Content-Type: application/xml
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<Request xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" CombinedDecision="false" ReturnPolicyIdList="false">
    <Attributes  Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject">
        <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">joe</AttributeValue>
        </Attribute>
        <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" IncludeInResult="false"> 
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">Manager</AttributeValue>
        </Attribute>
    </Attributes>
    <Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource">
        <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">MissionManagementApp</AttributeValue>
        </Attribute>
        <Attribute AttributeId="urn:thales:xacml:2.0:resource:sub-resource-id" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">Team</AttributeValue>
        </Attribute>
    </Attributes>
    <Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action">
        <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" IncludeInResult="false">
            <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">manage</AttributeValue>
        </Attribute>
    </Attributes>
    <Attributes Category="urn:oasis:names:tc:xacml:3.0:attribute-category:environment" />
</Request>
HTTP/1.1 200 OK
Content-Type:application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17">
    <Result>
        <Decision>Permit</Decision>
    </Result>
</Response>
Request

Request URL: POST /domains/{domainId}/pdp

Transfer Parameters
Name Required Parameter Type Object Type Description
X-Auth-Token Yes Header String Authorization token
domainId Yes URI String Security Authorization Domain Id
xacml request Yes Body String XACML 3.0 Request

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"
        }
      ],
      "longProductDescriptions": [
        {
          "langCode": "de-de",
          "description": "Lorem Ipsum"
        },
        {
          "langCode": "en-us",
          "description": "Lorem Ipsum"
        }
      ]
    }
  ]
}

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"
      }
    ],
    "longProductDescriptions": [
        {
          "langCode": "de-de",
          "description": "Lorem Ipsum"
        },
        {
          "langCode": "en-us",
          "description": "Lorem Ipsum"
        }
      ]
  }
}

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

Request specific major version 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/programversions/2019/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>/programversions/{major}/binary

Transfer Parameters

Name Required Parameter Type Object Type Description
product_id Yes Resource int Product ID
major Es Major string Major version

Response

The response contains the binary file.

Common Status Codes Returned

Code Description
200 OK
404 Binary, asset or version 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 No Body string true or false
category_id Yes Body int Category ID
long_product_description_en-us No Body string Long product description in English

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
long_product_description_en-us No Body string Long product description in English

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

Request manifest file for one specific asset's version

Get the manifest file for one specific version of a vf-OS Asset.

GET https://vfos-datahub.ascora.de/v1/products/1337/programversions/2019/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 products-route with the ID of the asset attached.

Request URL: GET /v1/products/<product_id>/programversions/<major>/manifest

Transfer Parameters

Name Required Parameter Type Object Type Description
product_id Yes Resource int Product ID
major Yes Resource string Major version

Response

The response contains the asset's manifest 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

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

Log in Developer

Log in as a developer to perform operations on its behalf.

POST https://vfos-datahub.ascora.de/v1/auth/developer HTTP/1.1
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "meta": {
    "status": true
  },
  "data": {
    "auth": {
      "userToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6eyJpYXQiOjE1NTMxNjkzMTUsImV4cCI6MTU1MzE2OTM3NSwiaXNzIjoiaHR0cHM6XC9cL2RhdGFodWIuYXNjb3JhLmRlIn19.eyJ1c2VybmFtZSI6ImhpbnpAYXNjb3JhLmRlIiwidXBzdHJlYW1Ub2tlbiI6ImV5SjBlWEFpT2lKS1YxUWlMQ0poYkdjaU9pSklVekkxTmlKOS5leUoxYzJWeUlqcDdJbWxrSWpvaWFHbHVlaUlzSW5KdmJHVnpJanBiSW05bVpteHBibVZmWVd"
    }
  }
}

Request

Request URL: POST /v1/auth/developer

Transfer Parameters

Name Required Parameter Type Object Type Description
username Yes Body string Username
password Yes Body string Password

Response

The response contains an Bearer-Token (userToken) that is required for further requests. This token has to be sent all following requests that shall be handled on the developer's behalf.

Common Status Codes Returned

Code Description
200 Developer authenticated
403 Invalid user credentials
500 Server error

Get Dependencies of an Asset

Get the dependencies (and optional sub-dependencies) of an asset.

GET https://vfos-datahub.ascora.de/v1/products/428/dependencies?sub_dependencies=true HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "meta": {
    "status": true
  },
  "data": {
    "dependencies": [
      {
        "productId": 427,
        "major": "1"
      },
      {
        "productId": 425,
        "major": "1"
      }
    ]
  }
}

Request

Request URL: GET /v1/products/<product_id>/dependencies

Transfer Parameters

Name Required Parameter Type Object Type Description
product_id Yes Resource int Product ID
sub_dependencies No Query boolean Include Sub dependencies

Response

The response contains all dependencies (and optionally the sub-dependencies) of an Asset.

Common Status Codes Returned

Code Description
200 OK
404 Asset or manifest of asset not found
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

The vf-OS Enablers (VE) are a set of solutions developed under the vf-OS' scope. The need for the development of VE is based on the industrial requirements of the vf-OS pilots. Some possible requirements that can lead towards the development of VE can be the need for notification, document sharing, multi-objective process optimisation, production events mapping to 3D map, fastest route calculation, data clustering and information mining, etc. In the scope of vf-OS, it will be developed 5 VEs.

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

  1. Configuration Enabler (CE - Enabler 1) provides the Version Control System designed to be interoperable with Enablers Framework and it'll be used by vf-OS Enablers.
  2. Notification Enabler (NE - Enabler 2) provides a notification system which follows the Enablers Framework's guide lines to be vf-OS interoperable.
  3. Quality Performance Evaluator Enabler (QPEE - Enabler 3) provides a quality and performance system to be used within the data stream between the vf-os platform and its assets.
  4. Smart Reporting Enabler (SRE - Enabler 4) provides to the vf-OS platform and assets a reporting system where the data can be agregated in order to create a user-friendly and easy-readable reports related to the data stream handled by the vf-OS platform.
  5. Dynamic Content Manager Enabler (DCME - Enabler 5) does provides a easy and user-friendly GUI to manage documents.

Enabler 1 - Get all Enabler's Configurations

GET /api/vf-os-enabler/v2/enabler/1 HTTP/1.1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    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

GET /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/configurations

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request
enabler_id Identifies the Enabler from the enablers pool

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

In the following Example it's queried all configurations related to enabler id 1:

{
    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,
        configname: "myconfigname",
        path: "this/is/my/path"
    },{
        _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,
        configname: "myconfigname",             path: "this/is/my/path"
    }]
}

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 name

GET /api/vf-os-enabler/v2/enabler/1/myconfigname HTTP/1.1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    result: "success",
    documents: [
    {
        _id: "2008518d34cfea1307rty876",
        __v: 0,
        created_at: "2017-08-07T12:00:00.000Z",
        body: [
            {"mongoport":"123"},
            {"loglevel":"debug"}
        ],
        nesting: [2,3],
        comment: "This is the second config version based on the previous one",
        parent: 1,
        active: true,
        enablerid: "1",
        version: 2,
        configname: "myconfigname",             path: "this/is/my/path"

    }]
}

Use this API call whenever is needed to retrieve one single configuration by a given configuration name. Note that each configuraiton version can have nested configurations. For example the Configuration version 3 can have nested the configuration version 1 and 2, which means all the key-value pair from version 1 and 2 will be present on the version 3.

Request

GET /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/<configuration_name>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request
enabler_id Identifies the Enabler from the enablers pool
configuration_name Identifies the configuration name from the configurations pool

Query Parameters

Parameter Description
resolvenesting Query parameter set to true to resolve the version nested

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.

In the following Example it's queried the configuration name myconfigname for the enabler id 1 :

{
    result: "success",
    documents: [
    {
        _id: "2008518d34cfea1307rty876",
        __v: 0,
        created_at: "2017-08-07T12:00:00.000Z",
        body: [
            {"mongoport":"123"},
            {"loglevel":"debug"}
        ],
        nesting: [2,3],
        comment: "This is the second config version based on the previous one",
        parent: 1,
        active: true,
        enablerid: "1",
        version: 2,
        configname: "myconfigname",             path: "this/is/my/path"
    }]
}

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 - Get Enabler's specific configuration name and version

GET /api/vf-os-enabler/v2/enabler/1/myconfigname/2 HTTP/1.1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    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,
        configname: "myconfigname",             path: "this/is/my/path"

    }]
}

Use this API call whenever is needed to retrieve one single configuration by a given configuration name and version.

Request

GET /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/<configuration_name>/<configuration_version>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request
enabler_id Identifies the Enabler from the enablers pool
configuration_name Identifies the configuration name from the configurations pool
configuration_version Identifies the configuration version from the configurations pool with the same configuration' name

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.

In the following Example it's queried the configuration version 2 from the configuration name myconfigname for the enabler id 1 :

{
    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,
        configname: "myconfigname",             path: "this/is/my/path"
    }]
}

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 - Create Enabler Configuration

POST /api/vf-os-enabler/v1/enabler/1/configurations/ HTTP/1.1
Accept: */*
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
X-Powered-By: Express
Date: Tue, 29 Aug 2017 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{"result":"success"}

Use this API call whenever is needed to create a new configuration version for one enabler.

Request

POST /api/vf-os-enabler/<api_version>/enabler/<enabler_id>/configurations

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request
enabler_id Identifies the Enabler from the enablers pool

JSON Body Payload

Name Required Type Description
version No String The configuration version that will be created. Example: 2
parent Yes String For historical purposes the parameter represents the version of the parent configuration file which the new one is based on. Example: 10
enablerid Yes String Enabler identification which the new configuration to be created belongs to. Example: ABC123
comment Yes String Configuration comment. Example: Base version
body Yes JSON JSON document where the custom configuration parameters are. Example: {"mongoport" : "123"}

Return Payload

The API response will contain a JSON document with the query result: success or error.

Example:

{
    result: "success"
}

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.

Enabler 2 - Register vApp

POST /api/vf-os-enabler/v0/register
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "appID":[
        "my_appID1"
    ],
    "developerID":[
        "my_developerID"
    ]
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

    "success": true,
    "data": {
        "token": "Z58oqMmXJJzC1KHAaPurgohg00xgklomu5DVXgcZwj4"
    }

Use this API call whenever is needed to create vApp.

Request

POST /api/vf-os-enabler/<api_version>/register

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.

JSON Body Payload

Name Required Type Description
appID Yes STRING String where is the appID.
developerID Yes STRING String where is the developerID.

Example of JSON body payload structure: { "appID": [ "TR3", "TR4" ], "developerID": [ "[email protected]", "[email protected]" ], }

Return Payload

The API response will contain a JSON document with the property success: true, false and the data if the success became false.

Example:

{
    "success": true,
    "data": [
        {
            "token": "CQegGDPYvXRSEc6aGS19D4yRNn0usWnS8tyiDNC6ji3"
        },
        {
            "token": "4q6xB8dsjwy9dv5NN4Thdd6zCO75K6SiF82aJHC45rb"
        }
    ]
}

Return Codes

Code Description
200 Register Vapp: Successfully.
404 App is already registered or AppID is Null.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Create Rules

POST /api/vf-os-enabler/v0/notification/rules
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "body":[
        {
            "appID": "AppID",
            "description": "Description",
            "parameter": "Parameter",
            "conditionValue": "Condition Value",
            "controlValue": "Control Value",
            "threshold": "Threshold",
            "notifyType": "Notify Type",
            "notificationType": "Notification Type",
            "hostname": "Hostname",
            "port": "Port",
            "path": "Path",
            "method": "Method",
            "emailTo":[
                "emailTo_1",
                "emailTo_2"
            ]
        }
    ]
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": [
        {
            "description": "Description",
            "reason": "Success"
        }
    ]
}

Use this API call whenever is needed to create a rule of vApp.

Request

POST /api/vf-os-enabler/<api_version>/notification/rules/

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.

JSON Body Payload

Name Required Type Description
appID Yes STRING String where is the vAppID.
description Yes STRING String where is the description.
parameter Yes STRING String where is the parameter for the rule.
conditionValue Yes STRING String where is the conditionValue (>, <, >=, <=).
controlValue Yes STRING String where is the controlValue.
threshold Yes STRING String where is the Threshold.
notifyType Yes STRING String where is the notifyType ("Email" or "HTTP Request").
notificationType Yes STRING String where is the Notification Type (1 - Notify End of Month, 2 - Notify End of Two Weeks, 3 - Notify End of Week, 4 - Notify End of Three Days, 5 - Notify Immediately).
hostname Yes STRING String where is the Hostname.
port Yes STRING String where is the Port.
path Yes STRING String where is the Path.
method Yes STRING String where is the Method ("POST", "GET", "PUT" or "DELETE").
emailTo Yes STRING Array of Strings where is the emails.

Example of JSON body payload structure: { "body": [ { "appID": "TR1", "description": "TR97", "parameter": "TR47", "conditionValue": ">", "controlValue": "47", "threshold": "20", "notifyType": "Email", "notificationType": 5, "hostname": "null", "port": 0, "path": "null", "method": "null", "emailTo": [ "[email protected]", "[email protected]", "[email protected]" ] }, { "appID": "TR1", "description": "TR87", "parameter": "TR57", "conditionValue": ">", "controlValue": "57", "threshold": "20", "notifyType": "HTTP Request", "notificationType": 0, "hostname": "teste", "port": 80, "path": "/api", "method": "POST", "emailTo": [ "[email protected]", "[email protected]", "[email protected]" ] } ] }

Return Payload

The API response will contain a JSON document with the property success: true, false and the reason if the success became false.

Example:

{
    "success": true,
    "data": [
        {
            "description": "TR97",
            "reason": "Success"
        },
        {
            "description": "TR87",
            "reason": "Success"
        }
    ]
}

Return Codes

Code Description
200 Rule created successfully.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Create Notifications

POST /api/vf-os-enabler/v0/notifications
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "token":"my_token",
    "body":[
        {"subject":"my_Subject_1",
         "subjectValue": "my_SubjectValue_1"
        },
        {"subject":"my_Subject_2",
         "subjectValue": "my_SubjectValue_2"
        },
        {"subject":"my_Subject_3",
         "subjectValue": "my_SubjectValue_3"
        }
    ]
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "reason": [
        {
            "subject": "my_Subject_1",
            "subjectValue": "my_SubjectValue_1",
            "total": 1,
            "results": [
                {
                    "ruleid": 1,
                    "success": true,
                    "comment": "Rule applied",
                    "notType": 5
                }
            ]
        }
    ]
}

Use this API call whenever is needed to create a new notification.

Request

POST /api/vf-os-enabler/<api_version>/notifications

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.

JSON Body Payload

Name Required Type Description
token Yes STRING String where is the token.
body Yes JSON JSON document where is the subject and subjectValue.

Example of JSON body payload structure: { "token": "string", "body": [ { "subject" : "stirng", "subjectValue" : "string" },{ "subject" : "string", "subjectValue" : "string" },{ "subject" : "stirng", "subjectValue" : "string" } ] }

Return Payload

The API response will contain a JSON document with the property success: true, false and the reason if the success became false.

Example:

{
    "success": true,
    "reason": [
        {
            "subject": "TR37",
            "subjectValue": "100",
            "total": 1,
            "results": [
                {
                    "ruleid": 1,
                    "success": true,
                    "comment": "Rule applied",
                    "notType": 5
                }
            ]
        }
    ]
}

Return Codes

Code Description
200 Notification created successfully.
404 There is no Rules for this vApp.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Get Apps

GET /api/vf-os-enabler/v0/getApps/[email protected]
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 13:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": [
        {
            "token": "token",
            "appID": "AppID",
            "developerID": "DeveloperID"
        }
    ]
}

Use this API call whenever is needed to retrieve all apps of developerid.

Request

GET /api/vf-os-enabler/<api_version>/getApps/<developer_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.
developer_id Identifies the Developer.

Return Payload

The API response will contain a JSON document with the property success: true, false and the data with the notifications of app (if found).

In the following Example it's queried the all Apps of specific developerID:

{
    "success": true,
    "data": [
        {
            "token": "0ahobLza90bTxNPF9wBYVOtMCoPOD8DMonijqthUila",
            "appID": "TR",
            "developerID": "[email protected]"
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 DeveloperID does not exist.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Get Rules

GET /api/vf-os-enabler/v0/getRules/myawesomeappid
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": [
        {
            "rulesID": ruleID,
            "description": "Description",
            "parameter": "Parameter",
            "conditionValue": "Condition Value",
            "controlValue": "Control Value",
            "threshold": "Threshold",
            "notifyType": "Notify Type",
            "emailTo": "Emails",
            "notificationType": notificationType,
            "hostname": "Hostname",
            "port": Port,
            "path": "Path",
            "method": "Method",
            "token": "Token"
        }
    ]
}

Use this API call whenever is needed to retrieve all rules related to vApp.

Request

GET /api/vf-os-enabler/<api_version>/getRules/<app_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.
app_id Identifies the APP.

Return Payload

The API response will contain a JSON document with the property success: true, false and the data with the rules of app (if found).

In the following Example it's queried all rules related to specific appID:

{
    "success": true,
    "data": [
        {
            "rulesID": 1,
            "description": "TR37",
            "parameter": "TR37",
            "conditionValue": ">",
            "controlValue": "37",
            "threshold": "10",
            "notifyType": "Email",
            "emailTo": "[email protected],[email protected],[email protected]",
            "notificationType": 5,
            "hostname": "null",
            "port": 0,
            "path": "null",
            "method": "null",
            "token": "0ahobLza90bTxNPF9wBYVOtMCoPOD8DMonijqthUila"
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 AppID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Get Notifications

GET /api/vf-os-enabler/v0/getNotifications/myawesomeappid
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": [
        {
            "notificationID": 1,
            "subject": "Subject = Value of subject",
            "date": "2018-06-29T17:03:50.000Z",
            "token": "0ahobLza90bTxNPF9wBYVOtMCoPOD8DMonijqthUila",
            "rulesID": 2
        }
    ]
}

Use this API call whenever is needed to retrieve all notifications of vApp.

Request

GET /api/vf-os-enabler/<api_version>/getNotifications/<app_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.
app_id Identifies the APP to show the notifications.

Return Payload

The API response will contain a JSON document with the property success: true, false and the data with the notifications of app (if found).

In the following Example it's queried the all notifications of specific appID:

{
    "success": true,
    "data": [
        {
            "notificationID": 1,
            "subject": "TR37 = 100",
            "date": "2018-06-29T17:03:50.000Z",
            "token": "0ahobLza90bTxNPF9wBYVOtMCoPOD8DMonijqthUila",
            "rulesID": 1
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 AppID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Get Statistics

GET /api/vf-os-enabler/v0/getStatistics/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": [
        {
            "statisticsID": 102,
            "date": "2018-07-05T13:07:35.000Z",
            "result": "true",
            "subjectValue": "80",
            "subject": "TR47",
            "rulesID": 80
        }
    ],
    "total": {
        "totalNotifications": 1,
        "totalNotificationsApplyByRules": 1,
        "averageValue": "80.00",
        "percentage": "100.00"
    }
}

Use this API call whenever is needed to retrieve all statistics related to Rule.

Request

GET /api/vf-os-enabler/<api_version>/getStatistics/<rule_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.
rule_id Identifies the Rule.

Return Payload

The API response will contain a JSON document with the property success: true, false and the data with the statistics of rule (if found).

In the following Example it's queried all statistics related to specific ruleID:

{
    "success": true,
    "data": [
        {
            "statisticsID": 102,
            "date": "2018-07-05T13:07:35.000Z",
            "result": "true",
            "subjectValue": "80",
            "subject": "TR47",
            "rulesID": 80
        }
    ],
    "total": {
        "totalNotifications": 1,
        "totalNotificationsApplyByRules": 1,
        "averageValue": "80.00",
        "percentage": "100.00"
    }
}

Return Codes

Code Description
200 Data Found.
404 RuleID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Delete vApp

DELETE /api/vf-os-enabler/v0/app/myawesomeappid
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 13:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": "Delete Vapp Successfully"
}

Use this API call whenever is needed to delete vApp.

Request

DELETE /api/vf-os-enabler/<api_version>/app/<app_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.
app_id Identifies the APP.

Return Payload

The API response will contain a JSON document with the property success: true, false.

In the following Example it's delete the vApp:

{
    "success": true,
    "data": "Delete Vapp Successfully"
}

Return Codes

Code Description
200 Delete Vapp Successfully.
404 AppID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 2 - Delete Rules

DELETE /api/vf-os-enabler/v0/rule/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2017 13:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "success": true,
    "data": "Delete Rule Successfully"
}

Use this API call whenever is needed to delete rule of vApp.

Request

DELETE /api/vf-os-enabler/<api_version>/rule/<rule_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request.
rule_id Identifies the Rule.

Return Payload

The API response will contain a JSON document with the property success: true, false.

In the following Example it's delete the rule:

{
    "success": true,
    "data": "Delete Rule Successfully"
}

Return Codes

Code Description
200 Delete Rule Successfully.
404 RuleID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Create Subject

POST /api/vf-os-enabler/subject/create/
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "name":"my_name",
    "description":"my_description",
    "userID":"my_userID"
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": Create Subjects: Successfully

}

Use this API call whenever is needed to create a new subject.

Request

POST /api/vf-os-enabler/subject/create/

JSON Body Payload

Name Required Type Description
name Yes STRING String where is the name.
description Yes STRING String where is the description.
userID Yes STRING String for User ID.

Example of JSON body payload structure: { "name":"Test", "description":"This is the description", "userID":"Thrinisha" }

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

Example:

{
    "Result": true,
    "Reason": "Create Subjects: Successfully"

}

Return Codes

Code Description
200 Create Subjects: Successfully.
400 Subject Name Already Exists.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Create Collections

POST /api/vf-os-enabler/collection/create/
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "name":"my_name",
    "subjectsID":"my_subjectsID"
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": Create Collections: Successfully

}

Use this API call whenever is needed to create a new collection.

Request

POST /api/vf-os-enabler/collection/create/

JSON Body Payload

Name Required Type Description
name Yes STRING String where is the name.
subjectsID Yes INT Integer for Subjects ID.

Example of JSON body payload structure: { "name":"Test", "subjectsID":"1" }

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

Example:

{
    "Result": true,
    "Reason": "Create Collections: Successfully"

}

Return Codes

Code Description
200 Create Collections: Successfully.
400 Collections Already Exists in this Subjects.
404 SubjectsID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Create Request

POST /api/vf-os-enabler/request/create/
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "collectionid":"my_collectionsID",
    "url":"my_url",
    "method":"my_method",
    "raw":"my_raw",
    "payload":"my_payload"
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": Create Request: Successfully

}

Use this API call whenever is needed to create a new request.

Request

POST /api/vf-os-enabler/request/create/

JSON Body Payload

Name Required Type Description
collectionid Yes INT Integer for collections ID.
url Yes STRING String where is the full url.
method Yes STRING String where is the method, can be: POST, GET, PUT, PATCH and DELETE.
raw Yes STRING String where is the raw, can be: application/json, text/plain, application/javascript, application/xml and text/xml.
payload Yes STRING String for the body content (payload).

Example of JSON body payload structure: { "collectionid":1, "url":"http://my_test.com/my/api/path", "method":"POST", "raw":"application/json", "payload":{"test":"test1"} }

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

Example:

{
    "Result": true,
    "Reason": "Create Request: Successfully"

}

Return Codes

Code Description
200 Create Request: Successfully.
404 CollectionsID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Create Conditions

POST /api/vf-os-enabler/condition/create/
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "description":"my_description",
    "keySubject":"my_keySubject",
    "keyCondition": "my_condition",
    "value": "my_value",
    "requestID":"my_requestID"
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": Create RequestConditions: Successfully

}

Use this API call whenever is needed to create a new request conditions.

Request

POST /api/vf-os-enabler/condition/create/

JSON Body Payload

Name Required Type Description
description Yes STRING String where is the description.
keySubject Yes STRING String where is the keySubject, can be: StatusCode, BodyLength, TimeResponse and custom key.
keyCondition Yes STRING String where is the keyCondition, can be: ==, >, >=, < and <=.
value Yes STRING String where is the value.
requestID Yes INT Integer for request ID.

Example of JSON body payload structure: { "description":"AnotherTest", "keySubject":"StatusCode", "keyCondition": ">", "value":"200", "requestID":"1" }

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

Example:

{
    "Result": true,
    "Reason": "Create RequestConditions: Successfully"

}

Return Codes

Code Description
200 Create RequestConditions: Successfully.
404 RequestID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Create Activity

POST /api/vf-os-enabler/activity/create/
Accept: */*
Content-Type: application/json; charset=utf-8

{
    "count":"my_count",
    "requestID":"my_requestID"
}
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": Create Activity: Successfully

}

Use this API call whenever is needed to create a new activity.

Request

POST /api/vf-os-enabler/activity/create/

JSON Body Payload

Name Required Type Description
count Yes INT Integer for count.
requestID Yes INT Integer for Request ID.

Example of JSON body payload structure: { "count":"123", "requestID":"1" }

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

Example:

{
    "Result": true,
    "Reason": "Create Activity: Successfully"

}

Return Codes

Code Description
200 Create Activity: Successfully.
404 RequestID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Create Performance Test

POST /api/vf-os-enabler/performance/Thrinisha/Subject/NameofCollections
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": [
        {
            "requestID": requestID,
            "requestConditionsID": requestConditionsID,
            "activityID": activityID,
            "Result": "Success"
        }
    ]
}

Use this API call whenever is needed to run performance test.

Request

POST /api/vf-os-enabler/performance/:userid/:subjectname/:collectionsname

URL Parameters

Resource Parameter Description
userid Identifies the User by ID.
subjectname Identifies the Subject by Name.
collectionsname Identifies the Collections by Name.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

Example:

{
    "Result": true,
    "Reason": [
        {
            "requestID": 1,
            "requestConditionsID": 1,
            "activityID": 1,
            "Result": "Success"
        }
    ]
}

Return Codes

Code Description
200 Performance test run successfully.
404 There is no Request Condition Record or There is no Activity Record or There is no Request Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Get Subject

GET /api/vf-os-enabler/subject/get/Thrinisha
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "data": [
        {
            "subjectsID": subjectsID,
            "name": "Name",
            "description": "Description",
            "userID": "UserID"
        }
    ]
}

Use this API call whenever is needed to retrieve all subjects related to User.

Request

GET /api/vf-os-enabler/subject/get/:userid

URL Parameters

Resource Parameter Description
userid Identifies the User by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the data with the subjects of user (if found).

In the following Example it's queried all statistics related to specific userID:

{
    "Result": true,
    "data": [
        {
            "subjectsID": 1,
            "name": "Test1",
            "description": "New Test",
            "userID": "Thrinisha"
        },
        {
            "subjectsID": 2,
            "name": "Test2",
            "description": "Test",
            "userID": "Thrinisha"
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 There is no Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Get Collections

GET /api/vf-os-enabler/collection/get/Thrinisha/Subject
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "data": [
        {
            "collectionsID": collectionsID,
            "name": "name",
            "subjectsID": subjectsID
        }
    ]
}

Use this API call whenever is needed to retrieve all collections related to Subject.

Request

GET /api/vf-os-enabler/collection/get/:userid/:subjectname

URL Parameters

Resource Parameter Description
userid Identifies the User by ID.
subjectname Identifies the Subject by Name.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the data with the subjects of user (if found).

In the following Example it's queried all statistics related to specific userID and subjectName:

{
    "Result": true,
    "data": [
        {
            "collectionsID": 1,
            "name": "Test1",
            "subjectsID": 1
        },
        {
            "collectionsID": 4,
            "name": "Test2",
            "subjectsID": 1
        },
        {
            "collectionsID": 6,
            "name": "Test3",
            "subjectsID": 1
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 UserID and/or SubjectName Incorrect or There is no Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Get Request

GET /api/vf-os-enabler/request/get/Thrinisha/Subject/Test1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "data": [
        {
            "requestID": requestID,
            "url": "url",
            "method": "method",
            "raw": "raw",
            "payload": "payload",
            "collectionsID": "collectionsID"
        }
    ]
}

Use this API call whenever is needed to retrieve all requests related to User, Subject and Collection.

Request

GET /api/vf-os-enabler/request/get/:userid/:subjectname/:collectionsname

URL Parameters

Resource Parameter Description
userid Identifies the User by ID.
subjectname Identifies the Subject by Name.
collectionsname Identifies the Collection by Name.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the data with the subjects of user (if found).

In the following Example it's queried all statistics related to specific userID, subjectName and collectionName:

{
    "Result": true,
    "data": [
        {
            "requestID": 1,
            "url": "http://teste.proxy.beeceptor.com/my/api/path",
            "method": "POST",
            "raw": "application/json",
            "payload": "{\"test\":\"test\"}",
            "collectionsID": 1
        },
        {
            "requestID": 2,
            "url": "http://my_test.com/my/api/path",
            "method": "POST",
            "raw": "application/json",
            "payload": "{\"test5\":2}",
            "collectionsID": 1
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 SubjectName and/or CollectionName Incorrect or There is no Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Get Conditions

GET /api/vf-os-enabler/condition/get/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "data": [
        {
            "requestConditionsID": requestConditionsID,
            "description": "description",
            "keySubject": "keySubject",
            "keyCondition": "keyCondition",
            "value": "value",
            "requestID": requestID
        }
    ]
}

Use this API call whenever is needed to retrieve all requestconditions related to Request.

Request

GET /api/vf-os-enabler/condition/get/:requestid

URL Parameters

Resource Parameter Description
requestid Identifies the Request by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the data with the subjects of user (if found).

In the following Example it's queried all request condition related to specific requestID:

{
    "Result": true,
    "data": [
        {
            "requestConditionsID": 2,
            "description": "code",
            "keySubject": "StatusCode",
            "keyCondition": "==",
            "value": "200",
            "requestID": 1
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 RequestID Incorrect or There is no Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Get Activity

GET /api/vf-os-enabler/activity/get/Thrinisha/Subject/Test1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "data": [
        {
            "activityID": activityID,
            "requestID": activityID,
            "method": "method",
            "count": count,
            "result": "Success"
        }
}

Use this API call whenever is needed to retrieve all activity related to User, Subject and Collection.

Request

GET /api/vf-os-enabler/activity/get/:userid/:subjectname/:collectionsname

URL Parameters

Resource Parameter Description
userid Identifies the User by ID.
subjectname Identifies the Subject by Name.
collectionsname Identifies the Collection by Name.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the data with the subjects of user (if found).

In the following Example it's queried all activity related to specific userID, subjectName and collectionName:

{
    "Result": true,
    "data": [
        {
            "activityID": 3,
            "requestID": 1,
            "method": "POST",
            "count": 3,
            "result": "Success"
        },
        {
            "activityID": 6,
            "requestID": 1,
            "method": "POST",
            "count": 3,
            "result": "Failed"
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 CollectionName Incorrect or UserID and/or SubjectName Incorrect or There is no Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Get StatusList

GET /api/vf-os-enabler/statuslist/get/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "data": [
        {
            "statusListID": 178,
            "date": "2018-08-24T16:22:09.000Z",
            "description": "Success",
            "information": "Expect: StatusCode == 200 Actual: 200"
        },
        {
            "statusListID": 188,
            "date": "2018-08-27T12:24:15.000Z",
            "description": "Success",
            "information": "Expect: BodyLength >= 10 Actual: 17"
        },
        {
            "Total": 2,
            "Success": 2,
            "Failed": 0,
            "Percentage": "100.00"
        }
    ]
}

Use this API call whenever is needed to retrieve all statuslist related to Activity.

Request

GET /api/vf-os-enabler/statuslist/get/:activityid

URL Parameters

Resource Parameter Description
activityid Identifies the Activity by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the data with the subjects of user (if found).

In the following Example it's queried all statuslist related to specific activityID:

{
    "Result": true,
    "data": [
        {
            "statusListID": 178,
            "date": "2018-08-24T16:22:09.000Z",
            "description": "Success"
        }
    ]
}

Return Codes

Code Description
200 Data Found.
404 ActivityID Incorrect or There is no Record.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Delete Subject

DELETE /api/vf-os-enabler/subject/delete/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": "Delete Subjects: Successfully"

}

Use this API call whenever is needed to delete Subject.

Request

DELETE /api/vf-os-enabler/subject/delete/:subjectid

URL Parameters

Resource Parameter Description
subjectid Identifies the Subject by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

In the following Example it's delete subject related to specific subjectID:

{
    "Result": true,
    "Reason": "Delete Subjects: Successfully"

}

Return Codes

Code Description
200 Delete Subjects: Successfully.
404 SubjectsID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Delete Collections

DELETE /api/vf-os-enabler/collection/delete/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": "Delete Collections: Successfully"

}

Use this API call whenever is needed to delete Collection.

Request

DELETE /api/vf-os-enabler/collection/delete/:collectionsid

URL Parameters

Resource Parameter Description
collectionsid Identifies the Collections by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

In the following Example it's delete collections related to specific collectionID:

{
    "Result": true,
    "Reason": "Delete Collections: Successfully"

}

Return Codes

Code Description
200 Delete Collections: Successfully.
404 CollectionsID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Delete Request

DELETE /api/vf-os-enabler/request/delete/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": "Delete Request: Successfully"

}

Use this API call whenever is needed to delete Request.

Request

DELETE /api/vf-os-enabler/request/delete/:requestid

URL Parameters

Resource Parameter Description
requestid Identifies the Request by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

In the following Example it's delete request related to specific requestID:

{
    "Result": true,
    "Reason": "Delete Request: Successfully"

}

Return Codes

Code Description
200 Delete Request: Successfully.
404 RequestID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Delete Conditions

DELETE /api/vf-os-enabler/condition/delete/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": "Delete RequestConditions: Successfully"

}

Use this API call whenever is needed to delete Collection.

Request

DELETE /api/vf-os-enabler/condition/delete/:requestconditionsid

URL Parameters

Resource Parameter Description
requestconditionsid Identifies the RequestConditions by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

In the following Example it's delete requestCondition related to specific requestconditionsID:

{
    "Result": true,
    "Reason": "Delete RequestConditions: Successfully"

}

Return Codes

Code Description
200 Delete RequestConditions: Successfully.
404 RequestConditionsID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 3 - Delete Activity

DELETE /api/vf-os-enabler/activity/delete/1
Accept: */*
HTTP/1.1 200 OK
Content-type: application/json
X-Powered-By: Express
Date: Tue, 29 Aug 2018 15:00:00 GMT
Connection: keep-alive
Transfer-Encondig: chunked

{
    "Result": true,
    "Reason": "Delete Activity: Successfully"

}

Use this API call whenever is needed to delete Collection.

Request

DELETE /api/vf-os-enabler/activity/delete/:activityid

URL Parameters

Resource Parameter Description
activityid Identifies the Activity by ID.

Return Payload

The API response will contain a JSON document with the property Result: true, false and the Reason.

In the following Example it's delete activity related to specific activityID:

{
    "Result": true,
    "Reason": "Delete Activity: Successfully"

}

Return Codes

Code Description
200 Delete Activity: Successfully.
404 ActivityID Incorrect.
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.

Enabler 4 - Get Report templates

GET /api/vf-os-enabler/v1/templates/owners_name HTTP/1.1
Accept: */*
HTTP/1.1 200 OK
Content-type: text/html
X-Powered-By: Express
Date: Tue, 29 Aug 2017 11:04:31 GMT
Connection: keep-alive
Transfer-Encondig: chunked

HTML PAGE

Use this API call whenever is needed to retrieve a specific template with dynamic report content inside.

Request

GET /api/vf-os-enabler/<api_version>/execute/<template_id>

URL Parameters

Resource Parameter Description
api_version Identifies the API version that will be used for the request
template_id The template identification of the report you want to generate

Return Payload

The API response will contain a html file with the report template inside including the data structured in a table visualisation format.

Return Codes

Code Description
200 Report generated
400 Bad request
404 Template not found
500 Internal Server Error - There was an unexpected error at some point during the processing of the request.