APIs¶
The restful Application Programming Interfaces (API) support analysis ready data distribution through a frame work of microservices that retrieve, subset, and convert the data into user community specific Analysis Ready Data (ARD) formats.
Changes from v1 to v2
- No longer able to request multiple file types in a single API request, where previously a link was provided in the outputs section of the JSON response. The API now streams the requested file type directly as a response object.
API Response Times Vary
The response times vary between the different service endpoints and server load a given time.
- As a general rule the higher the temporal level (Daily vs a Climatology) and the greater number of parameters requested will slightly slow down the API's response.
- Using a global or regional tool will result in a greater number of data values returning causing the API's response to be significantly slower than a single point request.
Service Architecture Diagram
Types¶
| Category | Description |
|---|---|
| Temporal | The APIs that return user community specific Analysis Ready Data (ARD) products. |
| Application | The APIs that return user specified reports and validation products that use the Temporal APIs. |
| System | The APIs that supply consistent configuration information across the APIs. |
API Response Times Vary
The response times vary between the different services and load a given time.
- As a general rule the higher the temporal level (Hourly vs a Climatology) and the greater number of parameters requested will slightly slow down the API's response.
- The Application API's are the slowest to respond; they typically include multiple temporal data request that run simultaneously. Additionally, have more intensive back end processing, but they requests will complete in under a minute.
Errors¶
POWER microservice API uses conventional HTTP response codes to indicate the success or failure of an API request.
| Code | Explanation | Description |
|---|---|---|
| 200 | Success | The request was successful. |
| 400 | Bad Request | The endpoint rejected the request do to incorrect inputs. |
| 401 | Not Authorized | Your user is Not Authorized to access the endpoint. |
| 404 | Not Available | The services is not available. |
| 429 | Too Many Requests | Too Many Requests. |
| 450 | Data Unreachable | The POWER Data Archive is unreachable. |
| 460 | Service Unreachable | The POWER API Services are unreachable. |
| 500 | Server Error | Something went wrong on our end; if it persists send a help ticket. |
| 502 | Bad Gateway | Something went wrong; if it persists send a help ticket. |
| 504 | Gateway Timeout | Something went wrong; if it persists send a help ticket. |
| 550 | Data Issue | An error occurred reading the POWER data; if it persists send a help ticket. |
400 Responses List Violations
The HTTP response code 400 lists all syntax and parameter violations in the response. Please review and make the necessary changes before resubmitting the request.
Rate Limiting¶
The POWER endpoints are rate limited to help prevent overloads of the services due to repetitive and rapid requests.If your application needs to request data from the POWER API at a higher rate than listed below please contact POWER Project Team and we will work to accommodate your application's needs.
| Services | Category | Limit |
|---|---|---|
| Climatology | Temporal | 60/min |
| Monthly | Temporal | 60/min |
| Daily | Temporal | 60/min |
| Hourly | Temporal | 20/min |