Civic Innovations

Roughly three years ago, Tim O’Reilly defined a vision for “Government as a platform.”

Today, there are around 240 API’s listed on Programmable Web that identify as “government” APIs. This number is sure to climb in the weeks and months ahead, as more and more governments, public authorities and agencies deploy APIs for developers to use.

One such API, recently released as part of the relaunch of Regulations.gov, got my attention when it was highlighted by Alex Howard of O’Reilly Media.

The Regulations.gov API is part of a broader effort to use new technology and social media to engage citizens in the public rule making process.

The rise of API-based programming, and the dramatic success of REST in recent years over other kinds of API formats (i.e., SOAP), has helped spur lots of innovation and even changed the way that people build software. It’s encouraging to see efforts like the Regulations.gov relaunch try and tap into this energy and grab some developer mindshare to spur innovation.

But if governments are going to attract developers with APIs, then it makes sense to look at government APIs and evaluate them against other, more commonly used APIs to see how they stack up. People respond to incentives, and developers are no different – if an API is well documented and easy to use, developers are more likely to give it a try. The more “friction” an API has, the less likely it is to attract developers.

How does the new Regulations.gov API measure up? I decided to take a few hours to give it a test and find out. Here’s what I found.

Sign me up!

The Regulations.gov API requires an API key to use – this is pretty common in the world of API programming, but Regulations.gov introduces some unneeded friction here.

Most widely used APIs built around PaaS offerings are largely self-service. They are set up to get developers up and running quickly with little or no need for “hands on” assistance from support staff. The process of signing up for a API key is usually frictionless – provide some basic information and a valid e-mail address and your off to the races.

I had to request a Regulations.gov API key using a plain old web form – submitting my name, phone number and e-mail address. This request was manually processed, and I received an e-mail back from support staff the next day asking me to identify the organization I represented.

I explained in my response that I was doing independent research and noted my intention to write about the experience of using the Regulations.gov API. Shortly thereafter, I received my API key and was able to start testing.

The reason for this process being manual is not obvious to me. I completely get the need to issue an API key, but surely this process can be automated. At present, the API is read only (via GET requests) so there isn’t all that much users can do currently other than run queries.

The entire process took about 1.5 – 2 days to complete – far too long in my opinion if I had intentions of using the Regulations.gov API at a hackathon or other civic hacking event. The event might have been finished by the time I got my API key to beging testing.

There doesn’t seem to be any reason why this process couldn’t take minutes rather than days. This seems like needless friction that will discourage many developers from giving this API a hard look.

The weak link in the chain

They say that a chain is only as strong as it’s weakest link. I say that an API is only as good as it’s documentation.

This is another area where I think the Regulation.gov API could be improved. The API docs are in PDF format, and are somewhat tedious to navigate. There are lots and lots of very good examples to emulate when designing API documentation.

Additionally, I found the names of some of the parameters used with API calls a bit cryptic – e.g., “Comment Period Start Date” is represented in an API call as ” cmsd”, while “Comment Period End Date” is represented as “cmd”. I realize this is a bit picky, but it would be much nicer if these parameters were more clearly named.

Less talk, more code

Overall, I found the Regulations.gov API easy to work with. In the course of a couple of hours, I reviewed the documentation, rans some quick command line tests to kick the tires a bit and then pounded out a rudimentary script.

Here is a simple Node.js script for querying the API and displaying the results. Complete code for this simple demo can be found here.

// Include required modules and config.
var http = require('http');
var util = require('util');
var config = require('./config');

// Search options.
var dct = process.argv[2] || 'O';
var a = process.argv[3] || 'EPA';
var cp = process.argv[4] || 'O';

// Options for HTTP  request.
var options = {
  host: 'regulations.gov',
  port: 80,
  method: 'GET'
};

// Build path to API endpoint.
var path = '/api/documentsearch/v1.json?dct=' + dct 
  + '&a=' + a 
  + '&cp=' + cp 
  + '&api_key=' + config.credentials.api_key;

options.path = path;

// Create HTTP client and make request.
var apiCall = http.request(options, function(response){

  // Simple string to hold response from API.
  var searchResult = '';
  response.on('data', function(chunck){
    searchResult += chunck;
  });
  response.on('end', function(){
    var doc = JSON.parse(searchResult);
    
    // Print out number of documens found.
    var docs = doc.searchresult.documents.document;
    
    // Write out Docket ID for each.
    util.puts('Search found: ' + doc.searchresult.recordCount + ' documents.');
    for(var i=0; i<docs.length; i++) {
      util.puts(docs[i].docketId);
    }
  });

});
apiCall.end();

One observation on the results returned from the document search endpoint – which this sample script uses – the document structure returned is somewhat complex and not especially well documented. I wasn’t easily discernable from the documentation what the structure of the result would be based on specific parameters included in the search (I opted for JSON as the result format).

As a result, when the default search options are changed (by passing in different arguments to the script when it’s executed) the resulting Docket ID listing is incorrect.

I might be missing something obvious, and it seems likely that this might be clearer to someone with a bit more familiarity with the structure of proposed regulations. But if the goal here is to attract mainstream developers to use the Regulations.gov API, then I think there is an opportunity to improve the documentation in this regard.

Overall, I really like what I see in the Regulations.gov API. If you haven’t had a play with it, I would encourage you to request an API and give the documentation a look.

It’s heartening to see the vision for “Government as a platform” becoming reality. Looking forward to more great APIs from government agencies.