RESTful Rails Development

Chapter 5. Designing APIs in RoR

In this chapter we will design a hypermedia API in RoR. We will first explore the principles of adaptable hypermedia interfaces and then see how to make resources explorable.

We will discuss the application flow that services should have, and we will talk about APIs in terms of actual interfaces instead of just sets of commands that you can learn by visiting a man page (or developer portal, in the case of web services).

Finally, we will make our Wikipedia categories API fully explorable.

Hypermedia and Adaptable APIs

In the API community, hypermedia is a hot topic capable of generating heated discussions. How should a hypermedia API be designed? What functionality should be implemented? What media types should be supported? Should new media types be defined? These are some of the questions that arise when talking about hypermedia APIs, and almost everyone seems to have different answers to them.

The whole concept of hypermedia is about making clients interact better with services, and making resources easily accessible and explorable.

Designing resources can be especially confusing, because the first question you need to answer is what exactly is a resource anyway?

Is a resource some table in a database? Is it something else? In reality a resource can be a bit of both. It can be a record in a database, but it can also contain information from other records, or from other databases or applications. A resource is essentially a gateway to some dataset. ...