Responses and Status Codes

All requests and responses are of an application/json content type and follow typical HTTP response status codes for success and failure.

  • 200 - Everything is OK
  • 201 - Created Successfully
  • 202 - Accepted
  • 204 - No Content
  • 301 - Moved Permanently
  • 400 - Bad Request
  • 401 - Unauthorized
  • 404 - Not Found
  • 500 - Internal Server Error

The API follows the general rule that all 200 codes are deemed successful, 300 codes denote a redirection, 400 codes are client errors and 500 codes are server errors.

In addition to the status codes the body of the response is formatted to the JSend standard as detailed below.

Success

A successful response is indicated by a HTTP status code in the 2xx range and will contain a status key of 'success' and a data key containing the body of the response (which optionally may be empty).

{  
   "code":200,
   "status":"success",
   "data":[  
      {  
         "key":"value"
      }
   ]
}

Errors

When an API call fails due to a client error or an unauthorized request is made a 4xx HTTP status code will be returned together with a message key of 'fail' indicating the conditions that caused the failure.

{  
   "code":400,
   "status":"fail",
   "data":{  
      "per_page":[  
         "The per page may not be greater than 100."
      ]
   }
}

When an API call fails due to an error with the server a 500 HTTP status code will be returned together with a message key of 'error' indicating the conditions that caused the error.

{  
   "code":500,
   "status":"error",
   "message":"Unable to communicate with database"
}

Types

Unless otherwise specified, all dates/timestamps from the API are returned in ISO 8601 format.

Decimal numbers are returned as strings to preserve full precision across platforms. When making a request, it is recommended that you also convert your numbers to strings to avoid truncation and precision errors.

Integer numbers such as unique identifiers used in each API are unquoted.

Pagination

Results that return arrays of variable length are paginated. The pagination response will include all variables as described below:

{  
   "code":200,
   "status":"success",
   "total":70709,
   "per_page":10,
   "current_page":1,
   "last_page":7071,
   "next_page_url":"https:\/\/api.triathlon.org\/v1\/athletes?page=2",
   "prev_page_url":null,
   "from":1,
   "to":10,
   "data":[  
      {  
         "key":"value"
      }
   ]
}

In all paginated requests the parameters 'per_page' defines the number of results to be returned per page and 'page' indicates the page number to be returned.


What’s Next