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

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

`REST`_ is an architectural style that, although introduced over a decade ago,
has recently picked up momentum in the software community. There is `lots of
debate`_ as to what REST `really means`_, what it `doesn't mean`_, whether many
`high-profile APIs claiming to be RESTful`_ actually are, and to what extent it
`even matters`_.

WDT's SMART API approaches the REST ideal in the following way:

* Clients use an HTTP verb (GET) to request resources (such as hail event and
  geometry data) stored by WDT.
* WDT servers respond with a stateless representation of the resource (such as
  JSON or XML).
* The client is responsible for any transition from one state (request) to
  another.
* The server's response provides the mechanism for doing so (embedded links at
  which related information may be obtained).

The API consists of multiple request types providing various content and levels
of detail. Most responses include at least one possible transition to further
information, as described in later sections. For simplicity's sake, all web
requests block until a response is fully served.

For now, the API must be invoked directly using REST, although client libraries
may be a consideration for future versions.

.. _authentication:

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

A method of authentication is needed to ensure that monetary charges for API
usage are processed correctly. This 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.

This method is not foolproof, since `IP address spoofing`_ may occur. However,
it does serve as a simple control mechanism for calculating invoices.
Detailed transaction logs are also kept for the purpose of verification.

.. _request_format:

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

In keeping with REST, requests are structured to ensure that resource
identifiers are globally unique. The generalized form of a URI is as follows::

    forensic.api.wdtinc.com/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
============

Unless otherwise specified, the following HTTP status codes may be returned in
the response header:

* ``200: OK`` - Returned under normal conditions (including if there are no events or reports)
* ``400: Bad Request`` - Returned if one or more *parameters* are invalid
* ``401: Unauthorized`` - Returned if `Authentication`_ fails
* ``404: Not Found`` - Returned if the resource does not exist (i.e., invalid *resourcePath*)

==========
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
.. _`IP address spoofing`: http://en.wikipedia.org/wiki/IP_address_spoofing
.. _`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

.. _`doesn't mean`: http://www.infoq.com/articles/rest-anti-patterns
.. _`even matters`: http://stage.vambenepe.com/archives/1700
.. _`high-profile APIs claiming to be RESTful`: http://www.nordsc.com/ext/classification_of_http_based_apis.html
.. _`lots of debate`: http://comments.gmane.org/gmane.comp.web.services.rest/14803
.. _`really means`: http://weblogs.java.net/blog/mkarg/archive/2010/02/14/what-hateoas-actually-means