Overview

At its core the Datawitness API is Modeled on the REST Architectural Style. We consider everything to be a resource and all resources are handled via HTTP. Information regarding REST as a design principle can be found here or here.

We chose to design this style of API because our goal is to make access to Datawitness as flexible and reliable as possible while at the same time not being directly influenced by any individual protocol, language or method which might constrain us in the foreseeable future. Thus, the internet itself is the model. We adhere loosely to this design and as such, this API can be described as a REST-based, and commonly as POX/HTTP (Plain Old XML over HTTP)

Security

At Datawitness, we consider our users privacy of the utmost importance so we have put together a security Best Practices list which every API developer should review before beginning development against our API. If we feel there is any abuse of our system via our API, access to our system will be denied and the offending client will be suspended pending a review by our staff.

Web Service URL

The Datawitness API has a single point of entry which every query passes through:


    https://api.datawitness.net/dw

Please note the use of https:// in the URL above. All Datawitness API communication is encrypted over SSL. Any non-secure requests are automatically rejected.

Authentication

After API access has been granted to a client the client will be given a unique SHA1 authentication token which is their API "key". For every API request you make, you’ll need to present this token in the form of a custom header. There is only one key available per client. This may change in the future to allow clients to perform different types of queries in the Datawitness Engine.

All API queries require authentication from the API itself, and from each user accessing their data through the Web Service. All responses are relative to the context of the authenticating user. For example, an attempt to query /dw/tags will query all tags only for the currently authenticated user.

Each user who wants to access Datawitness services through a third-party application must first authorize the third-party application. This process allows the Datawitness user to allow/deny access to their account from any individual API at any time and ensures that a third-party application cannot request a user's data without the user first granting it permission to do so on the user's behalf. More information regarding this can be found in the Authentication process details section.

HTTP Digest Authentication is the only supported authentication scheme for user accounts. When authenticating a user via Digest Auth, a user/password combination unique to the user + API is used.

Representations

All API requests are structured as URL's and all responses are in XML. Actions are determined via the http method used.

Notes regarding our XML format:

XML always contains a BOM
XML is UTF-8 encoded
XML has a Content-Type of "application/xml"
XML time values are always in Unix Timestamp format

Standard Success Message

A successful request to the API will return the following XML:


    <?xml version="1.0" encoding="UTF-8"?>
    <response status="ok">
    [RETURN VALUES(S)]
    ...
    </response>

Standard Fail Message

A failed request to the API will return the following XML:


    <?xml version="1.0" encoding="UTF-8"?>
    <response status="fail">
    <error>[ERROR MESSAGE]</error>
    ...
    </response>

DataWitness API 1.1 (Beta)