Scope

This REST API is provided

• either for data stored in a Measurement Database for a Health Dashboard (HD)
• or for data stored in a Central database for an Engineering Dashboard (ED)

Discovering the REST API

A simple Web Application is available to discover the REST API.This web application can be accessed with the following URL:

http://{host}/{WAR}/static/default.html.

This Web application allows you to test REST URIs, check JSON response, and use the "preview" form to navigate a resource to linked resources.

Uniform Resource Identifiers

All URIs are relative to a domain of a REST Server.  Therefore, a REST client must always concatenate an URI with the URI of the REST Server.For example, if the REST Server URL is:

 http://localhost:9090/Dashboard-WebService,

and the URI is AAD/applications, then the REST server is invoked with the following URL:

http://localhost:9090/Dashboard-WebService/rest/AAD/applications

URI Templates

URI templates notation is specified below  (see also http://tools.ietf.org/html/rfc6570):

• {string} notation:
  this syntax denotes a string expansion. 
• {?parameters} notation: 
  this syntax denotes an optional parameter to expand. The URL template is expanded as follow:
  
  • append "?" to the result string if this is the first defined value or append "&"
  • append the parameter name
  • append "="
  • append a parameter value which is a list of items, with "," as a separator (brackets separators are optional) 
    
    

Request Patterns

POST, PUT, DELETE payloads are always a collection of resources. Note that a resource is an item with an "href" attribute.

Resource Representation

Media Types

This REST API supports the following media-type:

JSON Representation

A JSON representation is a structure compliant with JSON format.Each property can be of type

• Array (a collection of items)
• String
• Integer (JSON number)
• Double (JSON number)
• Number 
• Structure (a nested structure)
• URI (a resource reference). 
• Date: JSON structure 
  • "time" attribute: date as a number of milliseconds  since 1970/01/01
  • "isoDate" attribute: date as an international date format "YYYY-MM-DD"

An hyperlink is denoted with 2 properties:

• href : a URI to the resource
• name: a name of the hyperlink

Each property specifies value occurrences:

• 0..1: an optional item
• 1: a mandatory item
• 0..*: an array of items or an empty array
• 1..*:  an array of items

Collections

Some URIs refer to a collection of resources.A resource can refer itself a collection of strings (see technologies)

Collections are ordered according to the items:

Configuration

REST API relies on

• Tomcat configuration files, 
• Spring configuration files
• and own configuration files

Configuration files

All configuration files settings are described in documentation related to AAD which embeds REST API.

Data Source/Domain

We can define several domains on each RDBMS Data Source.

Following names are reserved and cannot be used as a domain name

• ping (deprecated, see user/ping)

• key (deprecated, see server/key)

• login (deprecated, see user/login)

• logout (deprecated, see user/logout)

• reload (deprecated, see server/reload)

• server

• user

Security

For GET actions, REST API filters data according to the user authorizations (see Dashboards documentation for more details on the configuration).

• Results, list of applications, list of modules, list of technologies, list of tags are filtered
• Domain resources and System resources are not filtered, even if the user does not have authorization on any application of this resource
• Categories are not filtered (as they do not depend on applications)
• Requesting a non authorized application returns an HTTP 403 exception (Forbidden)
• Requesting a resource on a non authorized application, such as  a module or snapshot returns an HTTP 403 status (Forbidden)

PUT, DELETE, UPDATE actions on tags and categories requires an ADMIN privilege, otherwise an HTTP 403 status is returned.

If authorizations are changed, memory cache must be reloaded to impact connected users.

Following URLs require ADMIN privilege, otherwise an HTTP 403 status is returned:

• /server/reload

• /server/key

License

A license key is required to get resources on a central domain.

In a case of a restriced license, license.xml file is applied for authorizations.

There are 2 exceptions. These following URLs depends on authorizations.xml settings:

• {Domain}/applications/{ApplicationID}/snapshots/{SnapshotID}/ifpug-functions

• {Domain}/applications/{ApplicationID}/snapshots/{SnapshotID}/ifpug-functions-evolution

HTTP Protocol

Authentication

Authentication is based on basic authentication on server side.

Login

Prior to any request, REST client must authenticate on behalf of the current end-user, using the "login" request. This request must contain an HTTP header containing the credentials UserName:Password encoded in base 64.

GET /.../rest/user/login HTTP/1.1
Authorization: Basic Y2FzdDpjYXN0

• If credentials are valid then the server replies: HTTP/1.1 200 OK 
• If credentials are invalid then the server replies: HTTP/1.1 470 Authentication required

Logout

The following request closes the current session and replies "HTTP/1.1 401 Unauthorized"

GET /.../rest/user/logout HTTP/1.1

Note: This URL is declared in WEB-INF\application-security.xml configuration file.

Test

To test if current client can access to the server, use the "ping" request

GET /.../rest/user/ping HTTP/1.1

Client Cache Management

In order to allow take benefit of navigator response cache on client side, each response is replied with a "ETag" directive header, using the cache loading date:

ETag: "application/json, text/javascript, */*; q=0.01:Mon Aug 19 17:04:16 CEST 2013"

Note: No cache control directive is sent to the client.

Upon request with directive "If-None-Match", the server compares the provided date with the cache loading date.

If they are equals, then the  server replies with HTTP status 304:

HTTP/1.1 304 Not Modified

API key

The API key is an alternative to the Basic Authentication mechanism.

A key is a secret text (it can be unique random text) stored in the security.properties file:

security.apikey=22b56696-7d59-11e9-8f9e-2a86e4085a59

Any client can use this key to authenticate any user, with a request containing two HTTP headers:

• X-API-KEY: a key matching the one in the security.properties file
• X-API-USER: a user name to get a role and authorizations

For example we can call the "server/reload" web service to refresh the REST API memory cache as follow:

C:>curl -k https://localhost:8080/Dashboard-WebService/rest/server/reload -H "X-API-KEY: 22b56696-7d59-11e9-8f9e-2a86e4085a59" -H "X-API-USER: admin" -v

The API KEY is required to bypass the SAML Single-Sign On protocol, for non-browser clients, and the Report Generator executed in a standalone mode or integrated mode.

Note that the user is granted with "ROLE_ADMIN" role when the API KEY is used.

X-Client HTTP header

This header can be set by any REST API client in order to identify the effective client in the audit trail, for example:

C:>curl -k https://localhost:8080/Dashboard-WebService/rest/server -H "X-Client: CURL" -H "X-API-KEY: 22b56696-7d59-11e9-8f9e-2a86e4085a59" -H "X-API-USER: admin" -v

Query Parameters Encoding

Query parameters must be encoded, especially if they contain some special characters such like : space, #, +, etc.

For example:

The following URL

http://localhost:8080/Dashboard-WebService/rest/AAD/results?technologies=(C++)

must be encoded as follow:

http://localhost:8080/Dashboard-WebService/rest/AAD/results?technologies=(C%2B%2B)

Note that the Simple REST Client (default.html) encodes parameters.

Errors

{ "cause": "...", ...

{ "cause": "...", ...

 JSON response example:

{"code": 1, "message": "Cannot process this request"}