Overview ======== Purpose and Scope ----------------- The WeatherOps™ Model API is an interface to WDT's Weather as a Service® platform designed for weather model forecast reporting. ---- Requests -------- Authentication ~~~~~~~~~~~~~~ Requests must use `basic authentication`_. Sign up for a username and password (also referred to as an application ID and key) at the `WeatherOps Marketplace`_. Up to five passwords may be in use at any time. This allows old passwords to be disabled without any downtime. Methods ~~~~~~~ All requests use HTTP GET. Details are provided in the endpoint descriptions. Parameters ~~~~~~~~~~ Some requests may have parameters in the URI query string. Details are provided in the endpoint descriptions. Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., ``YYYY-MM-DDThh:mm:ssZ``). Resource identifiers use UUIDs and are represented as strings in 8-4-4-4-12 format. .. _headers: Headers ~~~~~~~ Requests must use the following Accept header, unless otherwise specified in the endpoint description. See `versioning`_ for further details. :: Accept: application/vnd.wdt+json; version=1 Requests must also include a `basic authentication`_ header. Requests may use an Accept-Encoding header to obtain gzip-encoded JSON: :: Accept-Encoding: gzip Examples ~~~~~~~~ Endpoint descriptions provide cURL examples to facilitate experimentation. CORS ~~~~ The API supports `cross-origin resource sharing`_, so that browsers can make requests using JavaScript served from any domain. ---- Responses --------- .. _status_codes: Status Codes ~~~~~~~~~~~~ The result of an API request can be identified by the status code returned. ============================= ========================================================================== Status Description ============================= ========================================================================== ``200 OK`` the request succeeded ``400 Bad Request`` the request body is syntactically invalid ``404 Not Found`` the specified resource does not exist ``406 Not Acceptable`` the Accept header is invalid ``422 Unprocessable Entity`` one or more request parameters are invalid ``500 Internal Server Error`` something is wrong on the server (contact support if the issue persists) ``503 Service Unavailable`` the API is unavailable (contact support if the issue persists) ============================= ========================================================================== Client error responses (codes 400-499) also have a JSON body that provides details about the cause of the error. :: { "id": "invalid_header", "message": "The media type in the Accept header is unsupported.", "url": "http://docs.api.wdtinc.com/model-api/en/latest/overview.html#headers" } Formats ~~~~~~~ All requests return minified JSON. Futher details and examples (pretty-printed for readability) are provided in the endpoint descriptions. Gzip-encoding of JSON responses is supported and recommended (see `headers`_). Unless specified otherwise, timestamps use UTC and are represented as ISO8601 strings (i.e., ``YYYY-MM-DDThh:mm:ssZ``). Resource identifiers use UUIDs and are represented as strings in 8-4-4-4-12 format. ---- .. _versioning: Versioning ---------- Version 1 is the current and only supported major version of the API. Minor and micro API versions (such as 1.1 or 1.0.1) should not be used in the Accept header. These may change frequently with backward-compatible URI, parameter, or header changes. Any future backward-incompatible changes will only occur under a new major version. This might include the addition, removal, reorganization, or renaming of endpoints. .. _`basic authentication`: http://en.wikipedia.org/wiki/Basic_access_authentication .. _`cross-origin resource sharing`: http://enable-cors.org/ .. _`WeatherOps Marketplace`: http://www.wdtinc.com/weatherops-apis