######
Design
######

========
Overview
========

The WeatherOps™ Archive API is an interface to our Weather as a Service® platform
designed for geospatial archive data.

.. _authentication:

==============
Authentication
==============

The API uses IP-based authentication.

Prior to using the API, the customer provides WDT with an IP address (or range
of IP addresses) from which the API will be invoked. WDT provides the customer
with a username and a hashed token. Then, on each API invocation, a lookup
occurs using the username and token parameters on the URI, in addition to the
inbound IP address provided by the request environment.  Access is granted if
these parameters match an authorization record stored by WDT for the specific
service requested. If not, a **401 Unauthorized** error is returned.

.. _request_format:

==============
Request Format
==============

The generalized form of a URI is as follows::

    http://base-uri/v2/resourcePath?parameters

Typically, the *resourcePath* portion of the URI is composed of:

1. A resource type corresponding to one of the supported requests
   (see following sections).

2. A geographic location, expressed as a lat/lon pair in `ISO 6709`_ format
   (*+DD.ddd-DDD.ddd*), or a geographic region, expressed as two lat/lon pairs
   in `ISO 6709`_ format joined together (*+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd*)
   representing the northeast and southwest corners.

3. In certain cases, a date in `RFC 3339`_ format (*YYYY-MM-DDThh:mm:ssZ*) or
   `POSIX time`_ (a.k.a. "epoch seconds").

Valid *parameters* include:

* **REQUIRED:** An account username (*u*) and authentication token (*t*).

* **OPTIONAL** (where it applies): A date range bounded by a beginning (*begin*)
  and ending (*end*) timestamp, both in `RFC 3339`_ format
  (*YYYY-MM-DDThh:mm:ssZ*) or `POSIX time`_ (a.k.a. "epoch seconds"). If
  unspecified, *end* defaults to now. The default for *begin* differs by
  request and is noted in later sections.

See individual request descriptions for example URIs.

===============
Response Format
===============

The default response format is either `JSON`_ or `GeoJSON`_, depending on the
request type. Where applicable, `KML`_ or `XML`_ may be requested using the
`Accept header`_ or by appending ``.kml`` or ``.xml``, respectively, to the end
of *resourcePath*, prior to the *parameters*.

The following are valid ways to obtain JSON using `cURL`_::

    curl forensic.api.wdtinc.com/v2/resourcePath?parameters
    curl -H "Accept: application/json" forensic.api.wdtinc.com/v2/resourcePath?parameters

The following are valid ways to obtain XML using `cURL`_::

    curl forensic.api.wdtinc.com/v2/resourcePath.xml?parameters
    curl -H "Accept: application/xml" forensic.api.wdtinc.com/v2/resourcePath?parameters

The following are valid ways to obtain KML using `cURL`_::

    curl forensic.api.wdtinc.com/v2/resourcePath.kml?parameters
    curl -H "Accept: application/vnd.google-earth.kml+xml" forensic.api.wdtinc.com/v2/resourcePath?parameters

============
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``           one or more request query parameters are invalid
``401 Unauthorized``          `Authentication`_ credentials are invalid or missing
``404 Not Found``             the specified resource does not exist (invalid path)
``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)
============================= ==========================================================================

==========
Versioning
==========

API releases are versioned using major, minor, and (if needed) micro revision
numbers, taking the form *major.minor* or *major.minor.micro*. These components
increment according to the following policy:

* **micro** - backward-compatible additions or changes to *parameters*
* **minor** - backward-compatible additions or changes to *resourcePath*
* **major** - backward-incompatible changes to *resourcePath* or *parameters*

The major revision appears in the URI to allow for future indication that
backward incompatible changes have been made relative to a prior release.
Backward-compatible API changes are continuously and transparently released
under the existing major revision.

.. _`Accept header`: http://en.wikipedia.org/wiki/List_of_HTTP_header_fields
.. _`cURL`: http://curl.haxx.se/docs/manpage.html
.. _`GeoJSON`: http://en.wikipedia.org/wiki/GeoJSON
.. _`ISO 6709`: http://en.wikipedia.org/wiki/ISO_6709
.. _`JSON`: http://en.wikipedia.org/wiki/JSON
.. _`KML`: https://developers.google.com/kml/documentation/
.. _`POSIX time`: http://en.wikipedia.org/wiki/Unix_time
.. _`REST`: http://en.wikipedia.org/wiki/Representational_state_transfer
.. _`RFC 3339`: http://www.ietf.org/rfc/rfc3339.txt
.. _`XML`: http://en.wikipedia.org/wiki/XML