Designing a RESTful API specification (part I)
When your business is about pushing and pulling data from an external system, or exposing your application domain to external clients, you often have two options: SOAP Webservices or a RESTful service. If you’re here there are great chances that you are ridding this new hype-age of web2.0 startups as if it was a new religion (just like us). But these preferences are not enough to achieve a successful job done, you must learn new concepts and “stay in the zone”.
Ok, so you need to design a RESTful API (and implement it later?), you must be asking “first what the hell is REST?” “Why you write RESTful?” “Or is it a mistake?”. Here we go. If you feel comfortable with the basic concepts please jump to the second part.
What is REST?
REST (REpresentational State Transfer) is a style or a set of principles for software architecture for distributed systems, nothing else, is not a specification neither a standard and neither an implementation.
Actually REST has a niche in applications over HTTP, but technically this is not a barrier.
– HTTP is a stateless protocol
– It defines a set of operations: POST, GET, PUT, DELETE
– Every resource has an universal address, the URI
– Hypermedia documents for modeling the information of a resource
What is a Resource?
A resource is nothing else than the objects that you expose, like an invoice, a paycheck or a blog entry.
The POST, GET, PUT and DELETE verbs map with the basic CRUD operations
POST -> Create
GET -> Read
PUT -> Update
DELETE -> Delete
A REST operation consists of:
– an URI identifying the resource
– a set of additional parameters
– a HTTP verb
– the response status code
– the information retrieved by the operation