Overview

HTTPS (port 443) protocol is enforced for all Core endpoints

Authentication

Token

Issued tokens are accepted as either URL token parameter or a X-EY-TOKEN header.

Both of the following cURL commands are accepted.

curl 'https://api.engineyard.com/requests?token=776418637f7f8b8d1d49c67be6bfff13'
          

or

curl -H 'X-EY-TOKEN: 776418637f7f8b8d1d49c67be6bfff13' 'https://api.engineyard.com/requests'
          

Parameters

POST/PUT/PATCH requests must be in the form of and submit an Content-Type header containing one of the following:

When issuing GET requests and no Content-Type is specified, responses with be in the form of application/json

In response to extra parameters, a 422 is returned with errors containing a list of error messages and unpermitted containing the list of unpermitted parameters. The rejected parameters may be nested.

Request

          Accept: application/json
          Content-Type: application/json
          
            
          {
            "account_id": "fc4edad4-fd8a-4fcd-a0ec-de3f24b14f17",
            "environment": {
              "name": "stefan",
              "snarfblat": "dinglehopper",
              "scruffy_looking": "nerf_herder"
            }
          }
            
          

Response

          Status: 422 Unprocessable Entity
          Content-Type: application/json; charset=utf-8
          
            
          {
            "unpermitted": [
              "snarfblat",
              "scruffy_looking"
            ],
            "errors": [
              "found unpermitted parameters: snarfblat, scruffy_looking"
            ]
          }
            
          

In response to missing parameters, a 422 is returned with errors containing a list of error messages and missing containing the first required paramter. The required parameters may be nested. Upon re-submission of the request, additionally requirements may be found.

Request

          Accept: application/json
          Content-Type: application/json
          
            
          {
          }
            
          

Response

          Status: 422 Unprocessable Entity
          Content-Type: application/json; charset=utf-8
          
            
          {
            "missing": "environment",
            "errors": [
              "param is missing or the value is empty: environment"
            ]
          }
            
          

Rate Limiting

For authenticated requests, you can make up to 2,000 requests per hour.

You can check the returned HTTP headers of any API request to see your current rate limit status:

$ curl -i https://api.engineyard.com/users/current
          
          HTTP/1.1 200 OK
          Date: Tue, 2 May 2014 14:50:41 GMT
          Status: 200 OK
          X-RateLimit-Limit: 2000
          X-RateLimit-Remaining: 1999
          X-RateLimit-Reset: 1399042800
          

The headers tell you everything you need to know about your current rate limit status:

Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

            
          new Date(1399042800 * 1000)
          // => Mon May 02 2014 15:00:00 GMT-0000 (EDT)
            
          

Once you go over the rate limit you will receive an error response:

HTTP/1.1 429 Too Many Requests
          Date: Tue, 2 May 2014 14:50:41 GMT
          X-RateLimit-Limit: 2000
          X-RateLimit-Remaining: 0
          X-RateLimit-Reset: 1399042800
          
          {
              "errors": ["API rate limit exceeded. See https://developer.engineyard.com/core/#rate-limiting for details."]
          }