Saga Documentation 0.9.434-4

SAGA REST API Conventions

Table of Contents

Security

All calls require SSL.

Data format

JSON.

Verbs

GET, POST, PUT, DELETE.

Authentication

REST and WebSockets APIs use JWT Tokens for authentication. Tokens have an expiry date. Users can have mutiple token. A token can be sent as the access-token header on REST requests, as a the Authorization header with the BEARER scheme or as an access-token URL query parameter.

Pagination Header

Most GET requests that list multiple records return an array of paginated results. The Link Header will give information on previous and next links. Currently, there is no total count of pages or records provided.

An example Link header:

Link: <http://{host}/users?page=1&limit=10>; rel="prev",<http://{host}/users?page=3&limit=10>; rel="next"
  • Note: Limit is currently ignored.

Used HTTP Statuses and Messages

Success Codes

200 - OK

Response contains the actual server response

Error Codes

The server responds with unified error messages if a request cannot be processed. Each response body contains at least name and the status_code, same as the actual http response status code.

400 - Bad Request

Request lacks proper query parameters.

{
  "status_code": 400,
  "name":"Bad Request"
}

401 - Unauthorized

Possible message variations:

  • Token Decode Error
  • Token Expired
  • Invalid Token
  • Missing User

Example

{
  "status_code": 401,
  "name":"Unauthorized",
  "message": "Token Expired"
}

403 - Forbidden

Possible message variations:

  • Unverified User
  • Insufficient Permissions

Example

{
  "status_code": 403,  
  "name": "Forbidden",
  "message":"Insufficient Permissions"
}

404 - Not Found

Requested resource does not exist. message may provide more detail.

Example

{
  "status_code": 404,
  "name": "Not Found",
  "message":"User does not exist"
}

422 - Unprocessable Entity

Contains additional data regarding the unprocessable data. errors contains key value tuples. The key is the name of the field, the value describes the issue.

Example

{
  "status_code": 422,
  "name":"Unprocessable Entity",  
  "message":"Script validation failed: title: Title is required.",
  "errors":{"title":"Title is required."}
}

500 - Unexpected Error

Unexpected server error. Message should contain more detail.

Example

{
  "status_code": 500,  
  "name":"Unexpected Error",
  "message":"Casting Error"
}

Next: REST API - External Resources