Authentication
First thing we need to be clear about is your method of authentication means nothing if you are not using https. If you are not using https then your users credentials can be snooped.
What is REST?
Representation State Transfer
Resource based
we are talking about thing(nouns) instead of actions(verbs)
resource is identified by the URI
The representation is not the resource, it is just a representation.
Representations
How resources get manipulated.
Part of the resource state.
JSON or XML
Example:
Resource: person
Service: contact_info GET
Representation: name, address, phonenumber (JSON/XML)
6 Constraints
Violating any of these except the optional code on demand, means your API is not strictly RESTful
Uniform Interface
A consistent interface between client and server
HTTP Verbs: GET, PUT, POST, DELETE
Uri’s: Resource names
HTTP Response: status, body
Stateless
Server contains no client state, each request has enough context for server to process in isolation
If there is state, it is kept on the client side
Client-Server
Assume a disconnected system
Separation of concerns
Cachable
Server response for representations
Implicit
Explicit – server specifies
Negotatiated – client and server negotiate
Layered System
Client does not assume direct connection
You don’t know where or how you are getting the data
Improvesscalability
Code on Demand
Server can temporararily extend a client, transfer logic to client
Client executes logic
An optional constraint
Rest API Allows
- Scalability
- Simplicity
- Modifiability
- Visibility
- Portability
- Reliability
Tips
HTTP Verbs similarity with CRUD
CREATE = POST
READ = GET
UPDATE = PUT
DELETE = DELETE
Use URL not query string
- Good: /users/12345
- Poor: /api?type=user&id=23
Design for your clients not your data
Use Plurals for consistency
- Recommended: /customers/33245/orders/8769/lineitems/1
- Not: /customer/33245/order/8769/lineitem/1
Use the correct HTTP Status Code Responses
Offer JSON and XML
Use hypermedia links
A key concept that is central to the idea of what REST really is.
Hypermedia links (HATEOS) or Hypermedia as the Engine of Application State make services more discoverable and self-descriptive
The client needs no prior knowledge about resources etc.
Documentation should not be a requirement to understand the API
So you can browse an API just like browsing the web <- that is restful
Client should not need to know how to interact with the data (hardcoded urls / resource names), the server should know this
So you can allow the html media type and you can really browse the api like you do the web
Effort required increases
Likely Requests and Responses
A list of HTTP methods and responses
Naming Resources
Use nouns
They should be predictable
Choose for clients not your data
Plurals: it is a debate but rather always user them
Idempotency
Basically an action can be applied to an object multiple times but applying it more than once will not change the state or result of it’s application.
Eg. Getting a cow pregnant
A GET never changes data so it is idempotent (Safe method)
PUT is idempotent as it updates an object with the same data, will return the same result
DELETE is idempotent, it will return a 404 – NB. It is better to mark for deletion instead of actually deleting
POST is NOT idempotent, as for every new POST there is a new different result
Sources: