General Notes

API Endpoint & Version

The Server running the API will be available on the following base URL :

 https://platform.cleverpoint.gr/api/v1

All the URLS from here on (POST/GET examples) will be given relative to the base URL.

API VERSION

The API version is embedded into the URL. The current version is 'v1' .

TEST Environment

The above base URL is for the PRODUCTION environment. For testing purposes the following URL is avaialble :

 https://test.cleverpoint.gr/api/v1

General URL Format

API URLs have the following general format:

 {base_url}/{resource}/{id}/{action|property}/?{params}

{base_url} :
is explained in the previous section and it is dependent on the PRODUCTION or TEST environment.

{resource} :
These URLs usually point to resources (either a list or a single object) such as /Shipments/ or /Customers/

{resource}/{id} :
These URLs point to a specific resource from a list of resources, for example a shipment URL can be: /Shipments/EC7AFB72-F5AA-4ED6-BB19-25DD07AF121A/

{resource}/{id}/{action|property} :
Some resources have actions and/or properties. {action|property} means that we can call (perform) an action or to get a property of the resource.

For example, a shipment object that has a Cancel action is called on the following URL: /Shipments/2D606CDE-1B28-4CF0-B441-48DD67821A51/Cancel/.

In case we need to retrieve a specific property value from an object (i.e. a related list of child items) then we can get the list by using a URL like: /Shipments/ 2D606CDE-1B28-4CF0-B441-48DD67821A51/AdditionalServices/.

The distinction between an action and a property is performed via different HTTP request methods. HTTP GET is always used to retrieve data and properties while HTTP POST will used when we need to perform an action.

/?{params} :
URL parameters that are specific to the request.

Data Format

The API supports only the JSON data format, consequently both Accept and Content-Type HTTP request headers must have the value of “application/json”.

The API accepts and returns Unicode characters, with the recommended charset being UTF-8. The only special case is \0 (null), which terminates the string.

Content Compression

Response body data may be compressed with gzip compression in order to minimize the amount of data being transferred over the wire. To request response body compression use the Accept-Encoding header on the request. The response will contain a Content-Encoding header specifying the gzip compression algorithm.

Type	Header	Value
Request	Accept-Encoding	gzip,deflate
Response	Content-Encoding	gzip,deflate

Request Methods

The API uses different HTTP request methods for each operation type category. The supported types are documented per case in the following chapters.

In general, the following HTTP methods can be used by API clients:

Method	Description
GET	Retrieve a single resource or a list of resources.
POST	Create/Modify resources, or perform an action on a resource or list of resources (i.e. Cancel action on a shipment).

Warning

PUT, DELETE and OPTIONS methods are not supported by this API version.

Response Status Codes

The API uses the standard HTTP status code classes, where a code from 200 to 299 signifies success. Request errors have status codes between 400 and 499, and server side errors have codes between 500 and 599. The following status codes are the most common used and returned by the API:

Success Status Codes:

Code	Description
200	OK Successful request.
201	Accepted. This header is used for long-running or asynchronous operations such as starting a server process. The header also implies that the request may not succeed and may be canceled.

Error Status Codes:

Code	Description
400	Bad Request. This status means that there is an error in the request. The request error may be data format error (invalid JSON) or an invalid value.
401	Unauthorized. The provided credentials are incorrect or missing.
403	Forbidden. The provided credentials are correct but the user is not permitted to complete the action. This status is used for either “permission” or “operation not allowed” error.
404	Not Found. The requested object does not exist. This error occurs when requesting non-existing resource. The resource may have never been created, or it may be deleted.
405	Method Not Allowed. This error occurs, when using incorrect HTTP method on an URL. For example PUT, DELETE and OPTIONS requests are not allowed and will return a 405 status.
429	Too many requests. Rate limits activated. See Rate Limits section

System Status Codes:

Code	Description
500	Internal Server Error. This status means a system error has occurred. Please contact support if you encounter such an error.
503	Service Unavailable. This status means that the system temporarily cannot fulfil the request or the system is out of capacity.

API errors usually contain a body which describes the error. Check the Messages & Error Handling section for a detailed explanation.

Rate Limits

The API server needs to impose call-rate limits to protect the infrastructure from being maliciously overloaded.

HTTP Verb	URI RegEx	Limit
GET	.*	1.000 / min
POST	.*	1.000 / min

The above limits may change in the future.

General Response Format

The API returns the requested results to the client in a response container. The generic form of the response is displayed below:

{
  "ResultType": "Success", 
  "Messages": [
    {
      "Code": "INFO_0001", 
      "MessageType": "Information", 
      "Description": "The detailed description of the message", 
      "DebugInfo": "Debug info goes here. i.e. stack trace"
    }, 
    {
      "Code": "WARN_0001", 
      "MessageType": "Warning", 
      "Description": "The detailed description of the message", 
      "DebugInfo": "Debug info goes here. i.e. stack trace"
    }
  ], 
  "Content": [
    {
      "StationId": "93db4879-2480-483a-a922-90df4b44968b", 
      "ShortName": "CleverPoint 14"
    }, 
    {
      "StationId": "e8dbbdab-6083-47cb-b200-e14723613e65", 
      "ShortName": "CleverPoint 13"
    }, 
    {
      "StationId": "b3306565-744d-4949-b045-a4f91ff255f2", 
      "ShortName": "CleverPoint 12"
    }, 
    {
      "StationId": "94aeb3ea-8434-4a9b-a5c2-b438d1feed8f", 
      "ShortName": "CleverPoint 11"
    }
  ]
}

Note

All the returned properties except ResultType are optional, i.e. if there isn’t any error and/or warning, the Messages property will be missing from the result.

The field ResultType provides the main outcome of the request. Available values are:

Value	Description
Success	OK. Successful request.
SuccessWithWarnings	OK. Successful request, but warnings were produced by the server. The returned Messages and/or Content properties can be examined if more details are required.
ActionRequired	Error(s) occured. Further action is required by the API’s client. Messages and/or Content should be examined.
Failure	Error(s) occured. Messages should be examined.

Messages is a list of Message objects which carry additional response information. When message(s) are generated by the request, either informational, warnings or errors, the server returns those messages as a list of objects. More information in Messages & Error Handling section.

Content is the main response data container. In case there is a list of returned objects this will be an array of objects, otherwise it will contain a single object. The content may vary according to the specific request documented in the following chapters.

Warning

The response container object is not returned in the response body in all cases. For example, when some client network error occurs and/or the request can’t reach the server, then the response container will be empty.

Note

All object properties that have null value are not present in the response. It is the client’s responsibility to set the default client side object properties to null in case those values are missing from the response.

Messages & Error Handling

When one or more errors occur, or additional information should be returned to the API client, they are returned as a list of objects where each item contains the following fields:

Field	Description
Code	The server code of the error or message.
MessageType	The type of the message. Valid values are: Information, Warning, Error and None.
ErrorPoint	Additional information regarding the point where the error occured. This can be a field name, a routine name, etc.
Description	The detailed description of the message.
DebugInfo	In case debugging is enabled on the server, debug information such as call stack trace etc. is contained in this field.

Error Handling

The presence of Messages in the response does NOT necessarily indicate that there is an error because there are cases where only informational and/or warning messages are returned from the server. Moreover, the absence of them does NOT indicate that the request is processed successfully because there are cases where HTTP errors occur before the server being able to produce messages.

In order for a client to properly determine if an error occurred, first and foremost, it needs to examine the HTTP response. If HTTP response is not equal to 2xx then there is definitely an error. Additional information may be present in response container’s Messages property. In case the HTTP response is equal to 2xx then the client should check the response container’s ResultType property and in case this is equal to Failure or ActionRequired then this is an application (business logic) error. Again, additional information may be present in Messages property.