Requests and errors

All API requests must be made over HTTPS with base URL https://api.amio.io/v1/. Data is sent and received in JSON format. Where possible, Amio API leverages appropriate HTTP verbs for requests.

HTTP Verb	Description
GET	Used for resource retrieval.
POST	Resource creation or any other non-idempotent operation.
PUT	Used for idempotent operation as collection replacement etc.
PATCH	Update resource. Use {"key": "value"} for property update or create and {"key": null} for delete.
DELETE	Deletes a resource.

Responses

HTTP status codes are used to communicate result of your request.

HTTP Status Code	Description
200 OK	The request was successful.
201 Created	The request was successful and resource was created.
204 No Content	The request was successful and resource was deleted.
400 Bad Request	When the request could not be understood.
401 Unauthorized	Unauthorized request, i.e. missing access token.
403 Forbidden	The request is forbidden due to security reasons.
404 Not Found	Requested resource cannot be found.
405 Method Not Allowed	Requested method was not allowed, some other HTTP method is required.
422 Unprocessable Entity	The request was understood but cannot be processed as some validation error might occur. This might also represent an invalid state of the application or other similar problems.
429 Too Many Requests	In case you exceed maximum number of requests within given period, you receive this error response for any consequent requests. See Rate Limiting for more details.
502 Bad Gateway	In case an underlying API responds with an error. For example this might occur when message is being send to Facebook Messenger and Facebook page is disconnected from Amio.

Location Header

All responses with status code 201 Created contain Location header with actual location of newly created resource, i.e. Location: https://api.amio.io/v1/channels/{channel_id}.

Errors

As the HTTP status code returns a basic information about an error, we provide additional data in response body for further error indication. All errors have following format:

Error Object

{
  "timestamp": "{{iso_8601_timestamp}}",
  "status": {
    "code": "{{HTTP_STATUS_CODE}}",
    "message": "{{HTTP_STATUS_MESSAGE}}"
  },
  "errors": ["{{LIST_OF_DETAIL_ERRORS}}"]
}

Generic Error

{
  "timestamp": "2016-12-21T11:17:56.397Z",
  "status": {
    "code": "405",
    "message": "Method Not Allowed"
  },
  "errors": [
    {
      "message": "Method POST is not allowed for resource /users."
    }
  ]
}

Validation Error

{
  "timestamp": "2016-12-21T11:17:56.397Z",
  "status": {
    "code": "422",
    "message": "Unprocessable Entity"
  },
  "errors": [
    {
      "field": "recipient",
      "rejected_value": null,
      "message": "Property 'recipient' cannot be null."
    }
  ]
}

Locale

Some resources use or return locale defining the language and region. The format is following {language ISO 639-1}_{region ISO 3166-2}, i.e. en_US for American english.

• Language is defined in ISO 639-1.
• Region represents country or subdivisions and is defined in 3166-2