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

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

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.