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."]
}