On May 9, 2013 the White House released an executive order with the title Making Open & Machine Readable the New Default for Government Information. My favorite line in the entire document is:

“Government information shall be managed as an asset throughout its life cycle to promote interoperability and openness, and, wherever possible and legally permissible, to ensure that data are released to the public in ways that make the data easy to find, accessible, and usable” (emphasis mine).

No Dumping
The usual approach to this type of work is to simply publish raw data in a directory or repository and then create some fencing around the data that helps track usage and distribution. Essentially, making government data “open” becomes a data dumping operation. This practice fails on all of President Obama’s three key points. First, data dumps make finding valuable information not at all easy. Second, even though the content might appear in a standard format like XML, CSV or JSON, it is hardly accessible (except for to geeks, who love this kind of stuff). And finally, raw data is hardly ever usable. Instead, it’s a mind-numbing pile of characters and quote marks that must be massaged and re-interpreted before it comes close to usability.

So, while this new directive offers an opportunity to make available a vast amount of the data the government collects on our behalf, the devil is in the details. And the details are in the interface – the API. As with poorly-designed kitchen appliances and cryptic entertainment center remote controls, when it takes extensive documentation to explain how to use something, the design has failed. There’s a simple principle here. Poor API design results in unusable data.

Affordable Data
It doesn’t have to be this way, of course. Government departments have the opportunity to implement designs that meet the goals set forth in the executive order. They can make it easy for people to find, access and use the data. They can publish not just data but APIs that afford searching, filtering and exploring the data in a meaningful and helpful manner; APIs that empower both users and developers to successfully interact with the data, without resorting to a dashboard featuring dozens of options or mind-numbing explanations.

In the (likely) event that the initial open data release consists of mere data, companies and individuals would be well advised to resist the temptation to build a multitude of “one-off” applications, each of which solves a single problem or answers a narrow set of questions for some subset of the data. Instead, work should be put into converting the raw data into usable API formats such as Atom, OData, HAL, Collection+JSON and HTML (to name just a few). APIs should be designed with the same care that would be given to any interactive experience.  Investment in tools and technologies that can properly represent the data in multiple formats while supporting various use cases and access requirements will yield great results.

Open Data APIs
In the end, organizations that know the importance of a good interface, the power of choice and the freedom of flexible representations will be able to convert raw data into valuable information, which can be consumed by a wide range of users, platforms and devices. These considerations are essential to building and supporting open data APIs.

Because – ultimately – data isn’t open, unless it’s “easy to find, accessible, and usable”.

My guess is you are familiar with the phrase “If you have to ask, you can’t afford it”. Well, that’s not what I mean here. Let me show you what I’m actually getting at…

If They Have to Ask…
Try this:

• Create a new Web API
• Get it up and running on some server or other
• Hand the single URL to a client dev and say: “There ya go!”

Is the API self-descriptive? Does it contain enough information in the responses to allow client devs to know what the API is for, what it is capable of and how they can make valid requests to the server and properly parse the responses?

Here are some questions for you:

• How many assumptions do you have about your API?
• Are these assumptions shared by client devs?
• All clients devs?
• Even ones who have never met you?

If your answer to any of those questions was “No” or “I’m not sure” then it’s likely that devs will need to ask you a thing or two about how to properly use your API. That’s no big deal, right?

…You Didn’t Afford It
In everyday life, if people have to ask how to use a device (television remote, toaster etc.) then you can be sure that device is “poorly afforded” – it’s a case of weak design. We all know devices (especially electronics) that come with huge manuals and complicated explanations – and we all know what a bummer it is when that happens.

In this respect, your API is the same as any other consumer device. It should be “well afforded” – developers shouldn’t have to read the technical equivalent of War & Peace before they are able to successfully use your API.

Yes, you can supply detailed instructions in prose, provide a long list of possible methods, include lots of tables etc. These resources are helpful for devs but they can be daunting to read and cumbersome to maintain.

Another approach is to include this kind of information in a machine-readable format – and one that most devs will also understand quickly. This can be achieved by providing instructions (that get automatically updated whenever your API changes) via hypermedia controls in the response. Why write a Web page of documentation to tell devs to construct a URI and use that URI to execute an HTTP GET when you can just include that (and much more) information in your API responses?

Help your client devs out. Throw ‘em a bone, here. Don’t make them read pages of documentation when you can just include simple run-time instructions as they’re needed.

In conclusion: If they have to ask, you didn’t afford it.

(Originally published on my personal blog.)

Numerous measurements exist for APIs. On the technical level, these metrics are fairly well understood. However, on the business level, there is a great deal of confusion over how the effectiveness of an API program can be accurately measured.

Layer 7’s March 14 webinar, ROI for APIs – which will feature input from TechCrunch and AT&T – should help to clear up some of this confusion. In particular, the webinar will focus on how hackthons can be used to gather valuable data for API ROI measurement.

How you measure your API ROI will depend on the purpose your APIs play in the greater business picture. Therefore, to provide a little primer for the webinar, I thought it would be helpful to give examples of a few API business models and how they might generate revenue.

• Per API Call
  Text messages sent via an API are billed at $0.01 per message
• Per API Payload
  Voice transcriptions via an API are billed at $0.01 per word
• Transactional Revenue
  An API call delivers a purchase
• Firehose API
  A monthly subscription provides unlimited API access
• Platform API
  An existing SaaS platform provides an API for partner integrations

To learn more, register for the webinar – ROI for APIs: Using Hackathons to Evaluate Your API Program featuring TechCrunch and AT&T.

I often get asked whether hackathons actually provide API publishers with any true, measurable return on investment (ROI). The simple answer is “yes” – and the positive benefits of hackathons are now undeniable.  However, the benefits can be a little hard to quantify, making ROI tricky to measure objectively.

For example, hackathons provide a fantastic way to grow developer awareness of your API as a brand in and of itself, separate from your core business. When the developers who attend your hackathon go back to their day jobs on Monday, they have added your API to their programming tool belts and will use it, when appropriate, in upcoming projects. Additionally, hackathons will attract the attention of thought leaders and influencers who will mention your API on blogs and forums, spreading the word further. These benefits can deliver considerable value but they can also be difficult to quickly quantify.

Nevertheless, API evangelists will be held accountable for demonstrating the real-world value of their hackathons. One way to do this is to show how hackathons enable your company to conduct developer user experience (DevUX) research at a minimal cost. Gathering feedback and data from hackathons provides the most cost-effective way to optimize the quality of your API as a product by answering questions like:

• How user-friendly is my registration process?
• Do my APIs ever return incorrect or unexpected results?
• What new features should I add to future versions of my API?
• Is the skill level of my API appropriate for long-tail app developers?
• What kind of tutorials and other documentation will my developers need?
• Which programming languages are my developers using to implement my APIs?
• How useful is my API and what are the most common/innovative use cases for it?

The data and feedback you gather will also help you to further demonstrate ROI by providing the answers to questions such as:

• How many developers registered and how many actually attended?
• Did the hackathon appeal to the types of developer we want to attract?
• Did any valuable or innovative apps get prototyped?

Hackathons offer a fantastic way to build excitement around your API and optimize the quality of your interface. If you still have any doubts, join us for a hackathon (and participate!) to see how other API platforms are doing it.

At the Layer 7 API Academy, we’ve had a few requests from API designers who are seeking strategies for handling large amounts of data in API responses.  Pagination is the most common method for addressing this scenario. Pagination, which is very common on the Web, allows API architects to conserve resources, improve response times and optimize the user experience. It’s a way of splitting up data into “pages” and is used in just about any API that returns collections of data.

I’ve released a short video tutorial titled Use Pagination in Web API Design to introduce the ins and outs of the interface. This video provides a crash course explaining pagination and outlining how to use it effectively in the design of Web APIs. I couldn’t fit all the implementation considerations I wanted in this six-minute tutorial, so watch out for a follow-up video on the subject.