Web APIs are an Anti-Pattern

[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

fielding-has-a-posse

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.

ref. ProgrammableWeb

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.

[TODO – mention Hydra –  plus hydra-middleware – via @bergi_bergos ]

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.
Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s