RESTful APIs

At Clojure-West, this past March, former ThoughtWorker Siva Jagadeesan spoke on on how to build good web APIs using Resource Oriented Architecture (ROA) and Clojure.

The talk isn't really specific to Clojure, but is really more a primer on REST APIs.

Rants about true REST versus REST-ish, REST influenced, or partially RESTful are not especially interesting. That's not what this is. It's a nicely pragmatic guide to the architectural patterns and why you might use them.

1. The swamp of POX (plain old XML, or more likely JSON, these days): At first glance, many, myself included, take REST to mean RPC over HTTP with XML/JSON.
2. URI: Start thinking in terms of resources.
3. HTTP: The HTTP verbs together with URIs define a uniform interface. CRUD operations are always handled the same way. So are error conditions.
4. Hypermedia (HATEOAS): Possible state transitions are given in the message body, allowing the logic of the application to reside (mostly? completely?) on the server side. The key here is "discoverability of actions on a resource."

RESTful Clojure by Siva Jagadeesan

More

• Richardson Maturity Model: steps toward the glory of REST
• Roy Feilding's REST paper
• Clojure tools for REST APIs: Bishop and liberator
• Christopher Miles on Bishop: Makes Your Web Service Shiny and Why Is My Web Service API Crappy?
• REST and designing APIs
• Clojure: Web Socket Introduction
• RESTful principles
• Exploring the implementation aspects of the REST architectural style
• BlueEyes
• What Makes a Great Open API?, a talk from OSCON 2012 by John Musser of ProgrammableWeb
• Atlassian REST API Design Guidelines
• The REST API Design Handbook
• A 2006 article, Tim Bray on REST
• Versioning: how to express this in a RESTful way? domain.org/myresource/version/1 implies that version 2 is a different resource. Would it be better to express versioning as an orthogonal dimension? A URL defines a resource, we set a header to ask for a version?