[draft – publish early/often…]
I know this sentiment has been expressed elsewhere, but I thought I should add my €0.02 (if I haven’t already). In short, most Web APIs aren’t Webby. If you need to call it an API you’re probably doing something wrong…
Thing is, APIs over HTTP continue to proliferate yet the vast majority have a fundamental flaw : they’re inherently incompatible. If you wish to say, programmatically post to Twitter and post to Facebook, you currently have to build separate blocks of code for each, each converting from your internal representation.
There is quasi-standardization. It’s typical to use standard HTTP methods (often limited to GET and POST) and use JSON as the payload. This is often described as being RESTful. Nothing could be farther from the truth.
The key bits that are missing are Identification of resources and Hypermedia as the engine of application state.
[TODO fill this out]
ref. Mike Amundsen, hypermedia
JSON is a very nice way of representing data. However for the Web, it lacks a crucial requirement: native support for links. It’s not hypermedia. But it can be made hypermedia fairly transparently using JSON-LD.
HTML is the definitive hypermedia, but its support for arbitrary data (the kind that APIs in general may wish to pass around) is rather clunky, see RDF-A, microdata, microformats.
The answer : just use HTTP (with your preferred representation(s)).
The inimitable Paul Downey (@psd) expresses this well by flipping it on it’s head: Web APIs Are Just Web Sites.
I’m biased by having used RDF for a long time, my preferred approach is to :
- use RDF representations internal to the app
- expose a Turtle representation (using content negotiation) alongside those of HTML etc.