Request Reference

Overview

The Doxpop Data API is a REST style interface. Response content can be XML or JSON; there has been some discussion about also supporting XHTML in the future. We support Basic authentication over HTTPS.

REST style interface

The Doxpop Data Web Service is a RESTful style interface. The gist of it is that we define "resources" like cases, people, courts. The API is then essentially a browsable, searchable interface into collections of these resources. The advantage of this approach is that it's largely self-documenting. For the customer, that means we can easily offer the same data in multiple formats (e.g., XHTML, XML, JSON) and they can go from browsing through it in a web browser to requesting it in XML or JSON. This greatly simplifies development.

Requests

Requests are submitted via HTTPS using the GET method. Operations will return multiple formats depending on what the customer requested. At the moment customers can request XML or JSON format with a MIME type extension (*.xml, *.json). In the future, we may also support the HTTP Accept header as a method to request the format.

Returned collections for search requests are limited to a maximum of 200 results. Client applications should keep track of how many resource items are returned and make additional requests with the offset parameter to get more results.

Authentication

The potential customers we have talked to were only interested in Basic Auth.

HTTP Basic Auth. This is the basic authentication specification that involves a username and password (a digest actually). The benefit of this approach is its simplicity and ubiquity. Basically every web browser and HTTP client created in the last decade supports this mechanism. The downside is that requests cannot be "pre-authorized" and shared with 3rd parties as can be done with request signing. We will use the HTTPS transport, because the username and password are sent in clear text with basic authentication.

The username for the demo API web service is "demo". The password is also "demo". Customers who are ready to connect to the production API can contact Doxpop at api-support@doxpop.com or toll-free 866-369-7671 to set up a username and password.

Encryption

Requests must be submitted via TLS encrypted HTTP (a.k.a. HTTPS). This precludes the possibility of stream inspection or intermediate processing.

It's possible at a later date that query request signing will be an alternate method of authentication. In such a case, optional unencrypted transmission would be a useful capability.

Resources

Since this a RESTful API, all data is represented by browsable "resources". Most customer inquiries will begin with the Actors/Cases resource which accepts several request parameters to narrow the set of resources according to the customer's interest. The URI for an Actors/Cases resource request is composed of the transport (HTTPS), host (api.doxpop.com), "/actors_cases", and format extension (.xml or .json) followed by any query string parameters. An example URI is:

https://api.doxpop.com/actors_cases.xml?fullname=smith,+diana&case_role=DEFENDANT

Request Parameters

Query string parameters are appended to a basic URI to specify the desired set of actors and/or cases the customer is interested in receiving. We currently support the following query string parameters:

Responses

Examples of URLs and the responses are available for XML and JSON formats.