This page documents the C2MON REST API, what it is capable of, and how to use it to integrate C2MON data into web applications.

Developed by	Justin Lewis Salmon
Status	Operational
Source code	SVN Link
Design documentation	Initial study document: https://edms.cern.ch/document/1462727/1 Presentation: https://edms.cern.ch/document/1465057/1

REST

Representational State Transfer (REST) is a set of guidelines for creating web services which allow networked devices to communicate with each other via HTTP. REST is oriented around clients making requests for data to a stateless server. Thus, the REST paradigm is a pull model, as opposed to the push model employed by clients of the core C2MON API.

Exposed Resources

Currently, the API exposes the following data (or resources) to the client:

Data tag values (including control tags)
Alarms
Commands
Device classes
Devices (and their properties/fields)

Data Format

Currently, the API responds in JSON format only. It is lightweight, easy to parse, easy to read and has great support on the web. Support for XML responses could be added in the future if the need arises.

The following is an example of the data format of a data tag:

{
  "id" : 160867,
  "description" : "PUISSANCE TOTAL 400KV ACTUEL",
  "value" : 86.3,
  "valueDescription" : "",
  "serverTimestamp" : "2015-01-20 13:13:18.784",
  "sourceTimestamp" : "2015-01-20 13:13:16.674",
  "mode" : "OPERATIONAL",
  "simulated" : false,
  "dataType" : "Float",
  "quality" : {
    "invalidQualityStates" : {
    },
    "existingTag" : true,
    "initialised" : true,
    "description" : "OK",
    "valid" : true,
    "accessible" : true
  },
  "alarms" : [ ]
}

URL Structure

It is possible to retrieve both the current live value and historical values of data tags.

Accessing Live Values

To retrieve live cache values from the server, the URL structure is as described in the following table:

Request	Description
`GET /datatags/{id}`	Retrieves a specific data tag.
`GET /alarms/{id}`	Retrieves a specific alarm.
`GET /commands/{id}`	Retrieves a specific command.
`GET /classes/{id}`	Retrieves a specific device class.
`GET /devices/{id}`	Retrieves a specific device.
`GET /devices/{id}/properties`	Retrieves all properties of a device.
`GET /devices/{id}/properties/{id}`	Retrieves a specific property of a device.
`GET /devices/{id}/properties/{id}/fields`	Retrieves all fields of a property.
`GET /devices/{id}/properties/{id}/fields/{id}`	Retrieves a specific field of a property.

Note: the API currently only supports GET requests (not POST).

Accessing Historical Values

To retrieve historical values from the server, the client need only append the string “/history” to the request URL and specify additional parameters defining the number and/or date range of records desired, as described in the following table:

Parameter	Description	Example
`records`	Retrieves a specific number of records.	`GET /datatags/1234/history?records=1000`
`days`	Retrieves all records for a number of days.	`GET /datatags/1234/history?days=5`
`to` / `from`	Retrieves all records between the specified dates.	`GET /datatags/1234/history?from=18-11-2014 15:00:945& to=17-11-2014 09:30:134`

Note: The date format for the to/from parameters is " yyyy-MM-dd HH:mm:ss ".

API Versioning

Inevitably, APIs change over time. It is important to ensure that changes to the API will not cause existing client applications to break. Therefore, the API is versioned in order to provide backwards compatibility in the future. To specify a particular API version, the client must send an "Accept" header of the following format:

application/json; version=c2mon.web.rest.api.v1

The server will then send a response that matches the request version. If no header is supplied, the latest version of the API will be assumed. The server will always indicate the API version in the "Content-Type" response header.

Error Handling

Should an error occur while processing the client request, the API will return a useful, meaningful and consumable error message to the client. The error message will be in JSON format, just like the format of all other resources. The API will return sensible HTTP status error codes (4xx series for client errors, 5xx series for server errors).

The JSON error body will look, for example, like the following (for a request for a non-existent data tag):

{
  "status" : 404,
  "message" : "No datatag with id 1223173 was found."
}

Error descriptions are generally descriptive enough to allow the client to understand the reason for the failure.

Security

Currently, the API does not require authentication, as it is not possible to execute commands and also because it is restricted to the TN. However, in the future, RBAC authentication may be implemented.

C2MON REST API Documentation