REST API Responses

All response bodies are JSON or JSON API encoded.

JSON:

A single resource is represented as a JSON object:

{
    "field1": "value",
    "field2": true,
    "field3": []
}

Below is a specific example of a single resource presented as a JSON object:

{
    "code": "CUST",
    "description": "Customer Transfers",
    "comments": []
  }

A collection of resources is represented as a JSON array of objects:

[
    {
      "field1": "value",
      "field2": true,
      "field3": []
    },
    {
      "field1": "another value",
      "field2": false,
      "field3": []
    }
]

Below a specific example of a collection of resources represented as a JSON array of objects:

[ 
  { 
    "code": "CUST01", 
    "description": "Customer Transfers", 
    "comments": [] 
  }, 
  { 
    "code": "CONTACT", 
    "description": "Contact Transfers", 
    "comments": 
      ["created_at": 2017-08-27T16:14:57Z", 
        "created_by": "xxname", 
        "comment": "updated transfer" }, 
        "created_at": 2017-08-28T15:19:34Z", 
        "created_by": "xxname", 
        "comment": "<p>adjusted</p> - ready to run"} 
      ] 
  }, 
    "code": "Invoice" ,
    "description": "Invoice Transfers", 
    "comments":[] 
  }, 
  ... 
]

JSON API:

A single resource is represented as a JSON API object:

{
  "data":{ 
    "id": "1", 
    type": "groups", 
    "attributes": 
      { "code": "codename", 
        "description": "description of group" 
      }, 
      relationships":{ 
        "comments": {} 
      } 
    } 
  } 
}

Below a specific example of a single resource JSON API object:

{ 
  "data": 
    [{ 
      "id": "8", 
      "type": "groups", 
      "attributes": { 
        "code": "CUST01", 
        "description": "Customer Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [] 
        } 
      } 
    }] 
  } 
}

A collection of resources is represented as a JSON API array of objects:

{ 
"data": 
  [ 
    { 
      "id":"1", 
      "type":"groups", 
      "attributes":{ //...this groups'attributes 
        "code": "codename", 
        "description": "description of group" 
      }, 
      "relationships": 
        { //...this groups'relationships 
          "comments": { 
            "data": [ 
              { 
                "id":"5", 
                "type":"comments" 
              }, 
              { 
                "id":"6", 
                "type":"comments" 
              } 
            ] 
          } 
        } 
    } 
  ], 
"included":  
  [ 
    { 
    "type": "comments", 
    "id": "5", 
    "attributes": { 
      "created_at": "yyyy-mm-ddThh:mm:ssZ", 
      "created_by": "author-name", 
      "comment": "text for the comment"} 
    }, 
    { 
      "type": "comments", 
      "id": "5", 
      "attributes": { 
        "created_at": "yyyy-mm-ddThh:mm:ssZ", 
        "created_by": "author-name", 
        "comment": "text for the comment" 
      } 
    } 
  ] 
}

Below a specific example of a collection of resources represented as a JSON API array of objects:

{ 
  "data": [ 
    { 
      "id": "8", 
      "type": "groups", 
      "attributes": { 
        "code": "CUST01", 
        "description": "Customer Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [ 
          ] 
        } 
      } 
    }, 
    { 
      "id": "2", 
      "type": "groups", 
      "attributes": { 
        "code": "CONTACT", 
        "description": "Contact Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [ 
            { 
              "id": "10", 
              "type": "comments" 
            }, 
            { 
              "id": "12", 
              "type": "comments" 
            } 
          ] 
        } 
      } 
     }, 
     { 
      "id": "5", 
      "type": "groups", 
      "attributes": { 
        "code": "INVOICE", 
        "description": "Invoice Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [ 
          ] 
        } 
       } 
     }, 
... 
], 
"included": [ 
  { 
    "id": "10", 
    "type": "comments", 
    "attributes": { 
      "created-at": "2017-08-27T16:14:57Z", 
      "created-by": "xxname", 
      "comment-text": "updated transfer" 
     } 
   }, 
   { 
    "id": "12", 
    "type": "comments", 
    "attributes": { 
      "created-at": "2017-08-28 15:19:34Z", 
      "created-by": "xxname", 
      "comment-text": "
adjusted
 - ready to run" 
    } 
  } 
]

Timestamps are in UTC and formatted as ISO8601.

Unset fields will be represented as a null instead of not being present. If the field is an array, it will be represented as an empty array - ie [].

HTTP Status Codes

We use HTTP status codes to indicate the success or failure of a request.

Success codes:

• 200 OK - Request succeeded. Response included
• 201 Created - Resource created.
• 204 No Content - Request succeeded, but no response body.

Error codes:

• 400 Bad Request - Could not parse the request
• 401 Unauthorized - No authentication credentials (token) provided or authentication failed
• 403 Forbidden - The Authenticated API user does not have access
• 404 Not Found - Resource not found
• 415 Unsupported Media Type - POST/PUT/PATCH request occurred without a application/json content-type
• 422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error
• 429 Too Many Requests - Request rejected due to rate limiting
• 500, 501, 502, 503, etc - An internal server error occurred

Errors

All 400 series errors (400, 401, 403, etc) will be returned with a JSON or JSON API object in the body and a application/json or application/vnd.api+json content-type respectively.

{ "message": "Not Found" }

500 series error codes (500, 501, 502, etc) do not return JSON or JSON API bodies.

Validation Errors

In case of validation errors on a POST/PUT/PATCH request, a 422 Unprocessable Entry status code will be returned. The JSON response body will include an array of error messages.

{ 
  "message": "Validation Failed", 
  "errors": [ 
    { 
      "message": "Field is not valid" 
    }, 
    { 
      "message": "OtherField is already used" 
    } 
  ] 
}