RESTful Web APIs

Chapter 8. Profiles

Over the past three chapters, I’ve built up a set of rules for designing a brand new API. There’s still some work to do on these rules, but I can now present them in something approaching their complete form:

• Is there a domain-specific standard for your problem? If so, use it. Document any application-specific extensions (Chapter 5).
• Does your problem fit the collection pattern? If so, adopt one of the collection standards. Define an application-specific vocabulary and document it (Chapter 6).
• If neither of those is true, choose a general hypermedia format. Break down your application into its state transitions. Document those state transitions (Chapter 7).
• At this point, you have your protocol semantics nailed down. The application semantics are all that remain. Are there existing microdata items or microformats that cover your problem domain? If so, use them. Otherwise, define an application-specific vocabulary and document it (Chapter 7).

The issue here is not whether to use “hypermedia.” Maze+XML, AtomPub, and HAL all use hypermedia to describe state transitions, but they use it in different ways to solve different problems. The issue is choosing a format that lets you represent the state transitions that make up your API.

HAL is great for read-only applications. Maze+XML is great for read-only applications that happen to be maze games. AtomPub is great for read-write applications that work more or less like weblogs. Move outside a format’s comfort zone, ...