HTTPS (port 443) protocol is enforced for all Core endpoints
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'
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.
Accept: application/json
Content-Type: application/json
{
"account_id": "fc4edad4-fd8a-4fcd-a0ec-de3f24b14f17",
"environment": {
"name": "stefan",
"snarfblat": "dinglehopper",
"scruffy_looking": "nerf_herder"
}
}
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.
Accept: application/json
Content-Type: application/json
{
}
Status: 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
{
"missing": "environment",
"errors": [
"param is missing or the value is empty: environment"
]
}
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."]
}