Skip to main content

REST Brief Intro

REST is an acronym for 'Representational State Transfer'. Yo, Represent. This meaning 'depict' or 'stand for'. State, as in the condition of the thing represented. And transfer meaning to pass from one point to another. It is a protocol, meaning it uses existing technology in a format understood by both client and server.

URI and URL overview

URI = scheme "://" service "/" version "/" resources [ "?" query ] [ "#" fragment ]

The URI should be lowercase, and have hyphens depicting spaces. So not 'NewcastleUponTyne' or 'newcastle_upon_tyne'. Instead it should be 'newcastle-upon-tyne'.

The service means hostname, any sub-domains etc. Also any sub applications, like /blog etc.

Version is like v{major version}, i.e. /v2/

Nouns

So in our language we have names of things, and things doing things. Words describing the attributes of things. But the main thing is the thing, as it were. A thing then would be a resource, whether it be users, products, articles, comments. You name it. Things usually belong in a hierarchy too, like /users/posts/comments. This is a hierarchical structure:

groups/group-id/members
groups/group-id/members/user-id -> individual information

So we have the idea of collections. index.html used to be used as the main page in a website. Really, the index is what it is; it should list the contents of the current directory. Same with REST. The slash in a url then means a hierarchy. You shouldn't really have a trailing slash though. Example, these are not the same endpoints:

http://example.org/test -> an individual bit of information
http://example.org/test/ -> a listing of information

Verbs

Here are some of the common verbs (doing words) in HTTP:

GET - retrieve
POST - create new
PUT - create if not exists or update existing
PATCH - partial update
DELETE - removal
HEAD - no body, good for checking existance of endpoint
OPTIONS - describe the endpoints resources (it might have GET, POST, PUT)