REST (Representational State Transfer) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. It has increased in popularity relative to RPC architectures such as SOAP due to the intrinsic de-coupling of client from server that comes from having a uniform interface between heterogeneous systems.
- Stackoverflow.com Wiki
Go to books ↓
Your data model has started to stabilize and you're in a position to create a public API for your web app. You realize it's hard to make significant changes to your API once it's released and want to get as much right as possible up front. Now, the internet has no shortage on opinions on API design. But, since there's no one widely adopted standard that works in all cases, you're left with a bunch of choices: What formats should you accept? How should you authenticate? Should your API be versioned?
Good API design is hard! An API represents a contract between you and those who Consume your data. Breaking this contract will result in many angry emails, and a slew of sad users with mobile apps which no longer work. Documentation is half the battle, and it is very difficult to find programmer who also likes to write.
Even the simplest APIs have a lot of considerations to be made. Once you’ve settled on a couple patterns that you can use across your entire API implementing it becomes easy. And your API consumers will be able to learn it quickly. Be consistent across your resources (one style for lists, one style for detail, consistent data structures) and pay attention to the anticipated usage context for each request.
If you want to build a true REST API, you should seriously consider using Content Negotiation for versioning. In this way, you prevent link bloat, and effectively decouple versioning from the identity of each resource.
In many of my applications, the UI and API gravitate towards task-oriented UIs. Instead of “editing an invoice”, I “approve an invoice”, with specialized models, behaviors and screens just for accomplishing that task. But what happens when we move from a server-side application to one more distributed, to be accessed via an API?
For the last few years, whenever somebody wants to start building an HTTP API, they pretty much exclusively use REST as the go-to architectural style, over alternative approaches such as XML-RPC, SOAP and JSON-RPC. REST is made out by many to be ultimately superior to the other “RPC-based” approaches, which is a bit misleading because they are just different.
For all intents and purposes HTTP and REST are just the implementation detail of the communication protocol. And unless the API you are exposing really maps well to resources which can be accessed as a tree like a filesystem or an object store like S3, treating REST like and end on itself just gets in the way and makes things more complicated than it should.