Designing a RESTful API specification (part I)

Gian Zas
February 27, 2009 | 2 min read

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.

HTTP Verbs:

The POST, GET, PUT and DELETE verbs map with the basic CRUD operations
POST -> Create
GET -> Read
PUT -> Update
DELETE -> Delete

REST Operations

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


Get our stories delivered to your inbox weekly.