Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Redirect
visiblefalse
locationDASHBOARDS:RestAPI Reference Documentation

Livesearch
spaceKeyDOC83
sizelarge
additionalpage excerpt
placeholderSearch the REST API documentation
typepage
labelsrestapi

 



Info
HINT: you may want to use double quotes ("search") to surround your search term if you are having trouble finding the term you need.



Panel

On this page:

Table of Contents

Resources and Services:

Children Display

Target audience:

  • CAST AI Administrators
  • Consumers of information via the REST API


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.

default_html.png


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

Requests

Content-Type: application/json

Content-Type: text/csv

Comment

GET .../{resources}/{ID}

Yes

No

Report a full representation of a resource

GET ../{resources}?{filters}

Yes

Yes

Report a collection of resources

Each item is a short representation of a resource

GET ../{ressources}-summary

Yes

No

Report resources counters

POST ../{resources}

Yes

No

Insert a collection of resources.

This action is not idempotent, each call will insert new items 

DELETE ../{resources}

Yes

No

Remove a collection of resources or items. 

PUT ../{resources}

Yes

Yes

Update a collection of resources.

This action is idempotent, a second call will not change anything 

In CSV mode, replace a collection of resources

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:

Media TypeResource Representation
application/jsonA JSON text (for all resources)
text/plain

A plain text (for file contents).

Info
Note this will only list the first 10 violations.


text/csv

A Comma Separated Value Text.

Separator is ";"

Decimal Separator is "."

Empty column is represented with "null" value.

application/vnd.openxmlformats- officedocument.spreadsheetml.sheet

An Excel document with "xlsx" extension

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:

CollectionsOrder
List of items with namesAlphabetic order of names
List of snapshots itemsNumerical order of snapshots, from the most recent snapshot to the less recent one
List of configuration itemsAlphabetic order of keys



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 the Health Dashboard which embeds REST API.

LocationDescription
META-INF/context.xmlData source configuration. Each datasource is a link to a RDBMS server.
WEB-INF/domains.propertiesREST API Domain configuration, linked to a data sources and a schema.
WEB-INF/web.xmlInitialization parameters.
WEB-INF/security.propertiesManage authentication modes and configuration for LDAP.
WEB-INF/user.propertiesManage "default authentication" mode users/groups.
WEB-INF/roles.xml

Assign a role to a user or group ("default authentication" or LDAP mode).

Available roles are:

  • ADMIN 
  • QUALITY_MANAGER (Action Plan - AED)
  • EXCLUSION_MANAGER (Violations Exclusion - AED)
WEB-INF/license.keyA license key required to access Dashboard Services schemas.
WEB-INF/authorizations.xmlAuthorizations applied for Measurement Service / Dashboard Service schemas.
WEB-INF/license.xmlAuthorizations applied for Dashboard Services schema access in case of a restricted license.
WEB-INF/ log4j2.xmlLog settings.

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.

Code Block
languagepowershell
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
Info

Notes:

  • a Set-Cookie HTTP header is sent back from the server in the first server response.
  • the HTTP/1.1 470 Authentication required code is a custom CAST error code, therefore, if you have a firewall that tracks and blocks unknown codes, you may need to create an explicit exception to allow this code

Logout

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

Code Block
languagepowershell
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

Code Block
languagepowershell
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:

Code Block
languagejavascript
titleExample
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:

Code Block
languagejavascript
titleExample
HTTP/1.1 304 Not Modified

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

HTTP StatusCodeExample of messagesCircumstances
400 Bad Request1Cannot process this request
  1. This URI is not recognized, for example: "GET D/applications/A/snapshots/S/action-plan/triggers" is requested with S not being a snapshot of application A
  2. In case of a GET operation, there is an inappropriate/unsafe value for a query parameter, or URI fragment. For example:
    1. "GET AAD/applications/A/snapshots/S/action-plan/triggers" - is requested with S not being a last snapshot
    2. "GET AAD/applications/A/results?snapshots=(-1)&snapshot-ids=(4,5)" - snapshots and snapshot-ids parameters are exclusive
2

Incorrect parameter

This request may return too many items. Query parameter 'rule-pattern=$any' is not allowed for CSV

This URI contains a query-string with an unexpected parameter value, for example: "GET AAD/applications/A/snapshots/S/action-plan/issues?startRow=1&nbRows=-1"- nbRows has an incorrect value.
3Resource not implemented for this domainDBMS schema of this domain is too old, an upgrade is required to use this feature
4Invalid content

In case of a PUT, POST, DELETE operation

  1. there is a JSON syntax error
  2. there is an incorrect property name, property type, property value
  3. there is an inappropriate/unsafe property value
  4. a property is missing
403 Forbidden1You are not allowed to access this data.A user has no access to these data according to the authorizations.xml file or license.xml file
404 Not Found1Resource not foundThis URI contains IDs matching no resource.
406 Not Acceptable1The requested media type is not appropriate for this resource

Representation Negociation failed. In other words, 'Accept' HTTP Header does not match any expected content type: 'application/json', 'text/csv', ...

Most of resources support a single representation (i.e. a single media type)

500 Internal Server Error1Run-time exception cause and call stackUnexpected exception
503 Service Unavailable1Server status: LOADING

Domains are being loaded into memory cache

2DBMS connections has failed or all domains loading have been abortedDBMS is not started, DBMS resources are not available, context.xml is not correct

 JSON response example:

Code Block
languagejavascript
titleExample
{"code": 1, "message": "Cannot process this request"}


Info
Note that unrecognized parameters in a URL (for example "application" spelt incorrectly in the URL "AAD/results?quality-indicators=(quality-rules)&select=(evolutionSummary,violationRatio)&snapshots=2017-12-19&aplications=TEST_APPLICATION") will cause the unrecognized parameter to be ignored. The remainder of the URL (assuming that it is correct) will return results. In the example given, the REST API would return results for all applications. In other words, no error code will be returned.