I always hear about “REST”, but what does it means exactly?
REST is an acronym for Representational State Transfer, but this doesn’t help at all. Actually, a loosy definition from Ben Ramsey is “any simple interface that transmits data over HTTP without an additional layer”.
Know let’s look at some characteristics of RESTful API. They are :
- Focus on accessing a diversity of resources (nouns), NOT actions (verbs)
- Every resource is uniquely addressable
- All resources share the same constrained interface for transfer of state (actions) and content types
- Must be stateless, cacheable, and layered
One great propery of RESTful API is they should have clean well-designed URLs, which means
- clear hierarchy
- hackable, can be reverse-engineered
- clear meaning and are not obfuscated
- can be very long or very short
They are based on CRUD (Read Update Create Delete) which is based on HTTP methods :
- GET : Transfers (“copies”) a representation from resource (server) to client
- PUT : Exact opposite of get – from client to resource
- POST : Has the same meaning as “paste after;” that is: “add to what you have; don’t overwrite it”
- DELETE : requests that the resource identified is destroyed or removed from public web
Now how to design a RESTful API? What’s the workflow?
- Your job is to extract true requirements : you need first to define real use-cases
- Start with Short Spec : 1 Page is Ideal
- Bounce spec off as many people as possible and listen carefully to their feedbacks
- Start to code it out as you gain confidence with your draft
- Write code often, even with unfinished spec. Code lives on as examples, unit tests.
This sounds pretty much like any best practices for development, but always good to hear it anyway.
Now let’s focus on a specific workflow for your API implementation.
- Determine your resources clearly (i.e all things you will need to access inside your app)
<code>/users <br clear="none" />/users/username <br clear="none" />/users/username/favorites<br clear="none" />/users/username/tags
- Decide what methods each resource will support
/users GET POST PUT<br clear="none" />/users/username GET POST PUT DELETE<br clear="none" />/users/username/favorites GET PUT<br clear="none" />/users/username/tags GET PUT
- Observe how resources links together
tags --> users
- Develop your data schemas
/users<br clear="none" />id<br clear="none" />username<br clear="none" />firstname<br clear="none" />lastname
- Rationalize and refactor your schemas
try to remove duplicates, clean relationships, etc.
- Choose the best content type/format to represent your schemas
Most popular content type are XML, JSON and plain text, but you should need MIME or other for images
To finish, there is a list of API Best Practices (c)
- Easy to learn
- Easy to use, even without documentation
- Hard to misuse
- Functionality should be easy to explain
- Names should be largely self-explanatory
- Names should be consistent: the same word should mean the same thing through the whole API
- API should be regular, have some symmetry
- a full example
- expected response of the example (in all formats)
- listing of error codes and what they mean
- versioning - and deprecation schedules
The documentation should be searchable HTML interface (no pdf)
- Class: what an instance represents
- Method: contract between method and its client
- Preconditions, postconditions, side-effects
- Parameter: indicate units, form, ownership
- No need to become a RESTafarian (a sort of REST extremist), but let's try to keep close to a RESTful design
- Having sensible resource names/paths (e.g.,
- Use both XML and JSON for a web API output (best is to be able to chose with extension .json or .xml)
- Focus on clarity. Your API implementation does not have to mimic your underlying application architecture.
Principle of Least Astonishment : User of API should not be surprised by behavior
_ It's worth extra implementation effort
_ It's even worth reduced performance
Here are the sources of this article, which is largely plagiary
37Signals "API design for humans" http://37signals.com/svn/posts/3018-api-design-for-humans/
Designing RESTful Web Applications : http://files.benramsey.com/talks/2007/phpworks/phpworks07-rest.pdf
Rest in practice dicsussion group : https://groups.google.com/forum/?fromgroups#!forum/restinpractice