I’m trying to find a good “elevator pitch” for building hypermedia APIs with HTML. How about this:

Don’t build an API – publish your data instead: easy to read for both humans (not just developers) and software, and easy to link to.

After providing read access, the next step is to enable others to modify your data, manually as well as through software. That’s what we would call an API, of course. But I think it helps if you focus on making your data available instead of starting with “let’s build an API”. (I’m tired of APIs, as explained in my Linked Data for better image search blog post.)

Once the data is out there, everyone can “surf your Web of content” (including search engines if you let them). And developers can write code to automate, to glue separate data sources together, to mash them up.

In my opinion, XHTML+RDFa is the best way to reach that goal. But even if you disagree with my choice of format, I hope you can agree with the general point.

Making data more visible has long been a favorite topic of mine. A decade ago, I wrote a simple PHP script that made it easy to browse an Oracle database, because I hated how my valuable data was hidden behind arcane Oracle tools or the sqlplus command line. (Apparently, some people are still using that script. I guess I should start working on it again, and add RDFa and JSON to it.)

Update: Mike Amundsen comments “don't just tell them what's there (data), show what they can do (actions)”. He’s right, this is missing from my pitch. Don’t stop at publishing your data – let people work with it, and make the actions as easy to discover as the data itself!

Update: See also Ruben Verborgh’s The lie of the API.