About the Valinso API

The Valinso API is a RESTful API, that uses a HTTP protocol for communication. HTTP GET, POST, PUT and DELETE methods are used to access the API.

How to start

To begin using Valinso API request API key from support team

API key

The API key is a secret key unique to each user that is used to access the API.

Keep the API key in secret, and never expose it in any public website's client-side code.

Authentication

All requests to the Valinso API are authenticated using API key

The API key is set in the header of the requests via HTTP api-key header. So if the API key is 5f4ec0c9cda34558c3c340d4c2aa50b9, then you need to add this header to the API request:

api-key: 5f4ec0c9cda34558c3c340d4c2aa50b9

Request endpoint

All API requests have to be sent to this URL:

https://vps3.valinso.nl/api/head/valinso_api/

API requests to a specific version is also available, e.g.:

https://vps3.valinso.nl/api/2.0.0/valinso_api/

Connecting by HTTP is available as well, but for security reasons, use of HTTPS is highly recommended.

Request parameters

Some mandatory parameters (like object identifiers) must be included in the request URL path:

GET /api/head/valinso_api/device/123

Additional parameters can be passed as GET variables:

GET /vends?offset=10&limit=5

For POST and PUT requests, a more complex data structure can be passed as JSON encoded data in the request body:

POST /vends

{"items":[...]}

Response body

The response body is always a JSON object that contains a response status code (identical to the HTTP status code) and the result of the action. If the status code is 200, then the action was successful.

{
   "code": 200, //Response status code
   "result":{
      //API method return data
	  //...
   }
}

Paging

Sometimes the response includes paging information to allow to browse larger result sets by adding offset and limit GET parameters to the request URL.

{
   "code": 200, //Response status code
   "result":[
	   {
	      //Item 11
	   },
	   {
	      //Item 12
	   }
   ]
   "paging": {
      "total": 12,  //Total items available
      "offset": 10, //Items skipped from the beginning
      "limit": 20   //Number of items per page
   }
}

Error response

If the API call is not successful, then the response code is not in the 2xx range and the result attribute contains an error description text (see exception for status code 422).

{
   "code": 404, //Response status code
   "result":"Item not found" //Error text
}

In general, response codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with Valinso servers.

Multiple validation errors (status code: 422)

To return multiple validation errors at once, an error response with status code 422 can be returned. The body of such response is different to all other error bodies ("result" key will contain an object, not a string) and will look similar to following example:

{
  "code": 422, //Response status code
  "result": {
    "errors": {
      "client_id": [
        "Client cannot be blank."
      ],
      "name": [
        "Name is too long (maximum is 50 characters)."
      ],
      "email": [
        "E-mail is not a valid email address.",
        "E-mail is too long (maximum is 100 characters)."
      ],
      "phone": [
        "Phone is too long (maximum is 20 characters).",
        "Phone must be a number."
      ],
    }
  }
}

Timestamps

All timestamps from the API are returned as integers in UNIX timestamp format.