Building RESTful APIs in practice

So you have read the dissertation of Roy Fielding about REST. You have seen all the slides, blogs and articles on the internet about REST, and you are ready for your first RESTful API. But it turns out that the "simple rules" aren't really that simple in practice. Just like playing chess or poker, the rules are one thing, playing the game is something different.

In this book, we will create a RESTful API for a Monopoly gaming site. How do we add users and user-defined boards, streets and cities? How do users "login" and how do we make sure users can only move when it's their turn to move. We will cover topics like using hypermedia and hypertext as the engine of state, and how this can be applied to our API. We will show you all the caveats and traps that new - and sometimes experienced - REST designers will fall for, and how to avoid them.

Note that this book is code-agnostic so it is a good read for all kind of developers out there. We won't show you the exact code on how to write the API yourself, but merely what the API should output to your clients or what clients should sent to our API. We will talk about why certain things are done the way they are done, and why you should avoid others ways on occasion.

After reading this book, you will have a more profound idea on how to apply a REST architecture in practice while not falling on back to XML-RPC or other type of protocols.

Contents of the book:

Please note that the contents and order is subject to change.

• About this book
• Introduction
• Introducing REST
• Building a RESTful API
• About the monopoly game
• Why chooce REST for our API?
• Desigining the API
• User Accounts
• Getting user information
• Why we don't hardcore URL's in our clients
• Mutating users
• Adding a new user
• Activating the user
• Deleting a user
• Other user actions
• Browsing your API through HTML
• The board
• Creating a new board
• Asynchroneous operations
• Displaying the board
• Modifying the board
• Put vs Patch
• Board hierarchy
• Representation of resources
• Using the board in our game
• Game play
• Creating new game
• Finding games to play
• Paginating your data
• Searching and filtering games
• Connecting to a game
• ETags & Optimistic locking
• Starting the game
• Playing the game
• Waiting for your move
• Gameplay
• HATEOAS in action
• Paying rent and buying stuff
• Chatting with others
• Other REST issues
• Dealing with transactions
• Content types
• Versioning your API
• Dealing with composite resources
• Using hypermedia formats
• Application vs resource state