Overview

API version V5 is available now. All the earlier API versions (1, 2 and 2.1) have been removed at this time. API V3 and V4 will be shut off on March 16, 2015.

In V4 we introduce multiple types of pagination. Click here to learn more.

Endpoints

You can find all of the API endpoints for your account at wwws.appfirst.com/api/

Global Response Codes

These are the response codes that our API’s return.

  • 200 – Success!
  • 400 – Bad Request. Either the request type is wrong or the arguments are wrong or missing. A response will be provided with details.
  • 401 – Unauthorized. The api key and email you gave us do not match.
  • 404 – Not Found. The url does not exist on this server.
  • 429 – Too many requests. Request of this resource has reached the limit.
  • 500 – Internal Server Error. Our fault.

Authentication

All our APIs, unless otherwise specified, require basic authentication. The username is the email of the account owner and the password is the api key which you can find under Administration – Profile. For example, to get the list of servers running on your system you would do something like:

curl --user EMAIL:API_KEY https://wwws.appfirst.com/api/servers/

You can do this by taking the string “YOUR_EMAIL:API_KEY” and encoding it with standard base 64 encoding. Set this string in the header of the request as the value to the key HTTP_AUTHENTICATION.

Data Encoding

When your calling an API that takes data, be sure to urlencode it first before uploading. For PUT and POST requests, you will need to also be sure to set the CONTENT_TYPE header to application/x-www-form-urlencoded.

When parameters specify themselves as a json encoded string, that means you must first serialize the data to json and then urlencode it.

All dates are represented as an number of seconds (integer) since the epoch January 1st, 1970.

API Rate Limit

When a client exceeds the rate limit for a given API endpoint, AppFirst API will now return an HTTP 429 Too Many Requests response code.

API rate limit takes effect in two ways. For every request, there’s a limit for total number of requests that can be made in an hour. For log detail and server data request, there is a limit for the amount of data that can be retrieved (bytes) in a hour.

Rate Limit HTTPresponse Headers

  • X-Rate-Limit-Limit: the rate limit ceiling for that given request
  • X-Rate-Limit-Remaining: the number of requests left for the 1 hour window
  • X-Rate-Limit-Reset: the remaining window before the rate limit resets in UTC epoch seconds

Size Limit HTTPresponse Headers

  • X-Rate-Size-Limit: the size limit ceiling for that given request
  • X-Rate-Size-Remaining: the number of requests left for the 1 hour window
  • X-Rate-Size-Reset: the remaining window before the size limit resets in UTC epoch seconds

API Error Code

From API Version 3, API request errors will be returned in a JSON like format.

{
  "errors": [
    {
      "code": 20,
      "message": "Rate limit exceeded"
    }
  ]
}

List of API Error Codes

Error code for Http 40* error, including 400 and 404. This is because of invalid requests.

  • 1 – Requested object doesn’t exist in Database. Usually it’s because of a wrong id.
  • 2 – Invalid API parameter type. For example, an Integer value was expected while a String was passed in.
  • 3 – Invalid API parameter format. For example, an invalid email address was provided.
  • 4 – The parameter provided can’t be parsed.
  • 5 – Missing parameter. A required parameter is missing.
  • 6 – Illegal parameters are provided which conflict with one another. For example, an end date less than start date was provided.
  • 7 – Illegal parameter cause database conflicts. For example, trying to create a user with an existing email address.
  • 8 – Function not supported. Client tried issue a change on the model which is not supported.
  • 9 – Permission denied. Client doesn’t have permission to execute the change.

Error code for Http 5** error. This is because requests can’t be processed internally.

  • 10 – Error parsing internal response.
  • 11 – Can’t complete the request.
  • 12 – No data is available or can be found.
  • 13 – Database error.

Error code for Http 429.

  • 20 – Too many requests. Rate limits have been reached.
  • 21 – Asking for too much data.