SMIP custom Data API access specification

Data API protocol is based on HTTPS (TLS 1.2) and RESTful architecture. Valid HTTP methods, content types and other HTTP headers are documented for each function separately in the following chapters.

Usual HTTP status codes are used to signal the success or failure of a request. Error responses may also contain a JSON message with detailed internal error codes and descriptions where applicable (see next chapters for details about errors and HTTP status codes).

A Web service URL looks as follows:

https://{API_HOST}/rs/{API_ID}/{API_VER}/instances/by_id/{INST_ID}/resource_or_service

In this case {INST_ID} must be replaced with the actual id of the instance we are calling. For other specifics see concrete use cases in the second part of this document.

API Client must send an appropriate API-KEY in each request.
API-KEY may be obtained by logging into SMIP's UI and using the Data API account manager application to create a new API account and API-KEY.
The API-KEY must be sent inside the Authorization HTTP header and may use:
- Basic: Authorization: Basic {BASE64(USER:PASSWORD)}
- Bearer: Authorization: Bearer {API-KEY}

SMIP administrator(s) add access to each instance per each API client as needed.
API clients may access a list of their authorized instances using User instance manager application.

In case of an error an appropriate HTTP status code is returned. On top of that a JSON response with SMIP error codes may be returned. Multiple SMIP errors may be returned in the array below (at least one error object will always be present when errors property is returned).

             
{
    "errors": [
        {
            "error_code": "ERROR_CODE_1",
            "error_message": "ERROR_MESSAGE_1"
        },
        {
            "error_code": "ERROR_CODE_2",
            "error_message": "ERROR_MESSAGE_2"
        }
    ]
}

HTTP status code	SMIP Error code (JSON)	Description
200 OK		OK
202 Accepted		Entries have been accepted and scheduled for execution.
400 Bad Request	1000	JSON parse error: not well-formed JSON.
400 Bad Request	1001	Important request/JSON properties are missing or null.
400 Bad Request	1002	Invalid JSON property or HTTP parameter value(s), e.g., out of bounds.
400 Bad Request	1006	Invalid timestamp format.
400 Bad Request	1009	JSON array contains unexpected null elements. Check also for possible redundant commas between elements or after the last element.
401 Unauthorized	1100	The `Authorization` header is missing or contains an invalid API-KEY.
401 Unauthorized	1101	API Account is disabled.
403 Forbidden	1200	API Client doesn't have access to the requested resource or service.
404 Not Found		Invalid API URL.
404 Not Found	1300	The requested resource (e.g., instance) could not be found (invalid resource id).
404 Not Found	1301	The requested real-time data from an instance could not be obtained - the device (e.g., xEMS) didn't return any valid results (may be disconnected or not responding due to some internal problems).
406 Not Acceptable		Request header "Accept" contains an invalid type.
415 Unsupported Media Type		Request header "Content-Type" contains an invalid type.
429 Too Many Requests	1400	Call limit reached: Too many service calls in a time unit.
500 Internal server error		Unexpected internal error occurred that wasn't intercepted by SMIP. If the problem persists, please send a notification to smip at 3-port dot si.
500 Internal server error	1500	Unexpected internal error occurred that was intercepted by SMIP. If the problem persists, please send a notification to smip at 3-port dot si.
400 Bad Request	1600	IoT not supported for selected instance
404 Not Found	1601	IoT Product not found
400 Bad Request	1602	Invalid thing selector
501 Not Implemented	1610	IoT is disabled in SMIP
any 4XX or 5XX	2000+	Custom use case specific error codes.

URL 1: https://tmpxems.smipcloud.com/rs/xems_api/v1_0/instances/by_id/{INST_ID}/drcs/controlload
URL 2: https://tmpxems.smipcloud.com/rs/xems_api/v1_0/instances/by_id/{INST_ID}/drcs/scheduleload
HTTP Method: POST
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request header: Content-Type: application/json
Request body: JSON payload as specified by the project documentation
Response content: JSON payload as specified by the project documentation

Specific error codes

HTTP status code	SMIP Error code (JSON)	Description
400 Bad Request	2001	Wrong request according to DRCS specification. Missing entries.
400 Bad Request	2002	Wrong request according to DRCS specification. 'id' is not string.
400 Bad Request	2003	Wrong request according to DRCS specification. 'load_control_interval' is not number.
400 Bad Request	2004	Wrong request according to DRCS specification. 'load_control_beginning' is not string 'YYYY-MM-DDThh:mm:ssZ' representing date-time
400 Bad Request	2005	Wrong request according to DRCS specification. 'interval_beginning' is not string 'YYYY-MM-DDThh:mm:ssZ' representing date-time.
400 Bad Request	2006	Wrong request according to DRCS specification. 'load_control_value' is not a number.
400 Bad Request	2007	Wrong request according to DRCS specification. 'load_estimated_value' is not a number.
400 Bad Request	2008	Wrong request. 'id' value is wrong.
400 Bad Request	2009	Wrong request. 'load_control_interval' is out of bounds (15<load_control_interval<1440).
400 Bad Request	2010	Wrong request. Too many load_control_interval items (max 96 allowed).
400 Bad Request	2011	Too many load_control_interval items. HEMS doesn't have enough schedule entries.

GET DemandLoadForecast

URL: https://tmpxems.smipcloud.com/rs/xems_api/v1_1/instances/by_id/{INST_ID}/dihs/DemandLoadForecast
HTTP Method: GET
Request header: Accept: application/json
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request body: NONE
Response body: JSON payload as specified by the project documentation

GET DRCapabilityForecast

URL: https://tmpxems.smipcloud.com/rs/xems_api/v1_1/instances/by_id/{INST_ID}/dihs/DRCapabilityForecast
HTTP Method: GET
Request header: Accept: application/json
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request body: NONE
Response body: JSON payload as specified by the project documentation

PUT DREvent

URL: https://tmpxems.smipcloud.com/rs/xems_api/v1_1/instances/by_id/{INST_ID}/dihs/DREvent/{DR_EVENT_ID}
HTTP Method: PUT
Request header: Accept: application/json
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request body: JSON payload as specified by the project documentation
Response body: NONE

DELETE DREvent

URL: https://tmpxems.smipcloud.com/rs/xems_api/v1_1/instances/by_id/{INST_ID}/dihs/DREvent/{DR_EVENT_ID}
HTTP Method: DELETE
Request header: Accept: application/json
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request body: NONE
Response body: NONE

GET DRReport

URL: https://tmpxems.smipcloud.com/rs/xems_api/v1_1/instances/by_id/{INST_ID}/dihs/DRReport/{DR_EVENT_ID}
HTTP Method: GET
Request header: Accept: application/json
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request body: NONE
Response body: JSON payload as specified by the project documentation

GET AggregatedTelemetry

URL: https://tmpxems.smipcloud.com/rs/xems_api/v1_1/instances/by_id/{INST_ID}/dihs/AggregatedTelemetry
HTTP Method: GET
Request header: Accept: application/json
Request header: Authorization: Basic {BASE64(USER:PASSWORD)} or Authorization: Bearer {API-KEY}
Request body: NONE
Response body: JSON payload as specified by the project documentation

SMIP custom Data API access specification

API in general

Protocol

Authentication

Authorization

JSON error responses

xEMS API use case

DRCS (API 1.0 and 1.1)