Introduction to the API
Work-in-Progress
We're in the process of moving our API documentation to this website. Documentation for some endpoints not included here can be found on our legacy API docs page.
#
VersioningThe ETM API is versioned as v3, but at the time of writing is not semantically versioned. While we seek not to change the public API in a way that would break clients, it's nonetheless constantly in development.
All paths to the API are prefixed with /api/v3
.
#
Response status codesAs a REST API, the Energy Transition Model uses a range of status codes to indicate the success or failure of the request.
Code | Reason |
---|---|
200 OK | The request was successful. |
201 Created | The request was successful and a new resource was created. Note that a number of API endpoints use 200 OK instead. |
400 Bad Request | The server was not able to process the request due to it being malformed. |
401 Unauthorized | The request was rejected due to not having permission to access the resource. |
404 Not Found | The resource requested does not exist at the current time. |
406 Not Acceptable | The Accept header did not specify a content type which can be generated by the server. |
422 Unprocessable Entity | The request was correctly formed (unlike a 400 Bad Request response), but contained errors which prevent it from being accepted. Typically an "errors" parameter will contain more information. See Errors. |
429 Too Many Requests | The request was rejected due to exceeding the API rate-limit. At the time of writing, the ETM has no rate-limits; while there are no plans to change this, but your application should be prepared. |
500 Internal Server Error | An error occurred with the ETM. |
#
ErrorsMany endpoints within the ETM will respond with useful error information if the received request could not be processed. This will be in the form of a 400..499
response code, and a JSON response containing an errors
key.
"error_keys" attribute
Some endpoints also provide an error_keys
attribute – used for localization on official ETM websites. This attribute is not considered stable, and may be subject to change in the future. Please do not rely on it in your own applications.