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.