RESTful Services

What is REST

• REpresentative State Transfer
• Sorry.... WHAT ?!?
• Roy Fielding's Ph.D Dissertation 
• An Architectural Style
• Explains scaleability of web as set of constraints

Constraints?

• Client Server
• Uniform Interface
• Layered System
• Cache
• Stateless
• Code on Demand

Rest API

• Lots of Questions
• How to structure URI
• How to name resources
• How to use HTTP Verbs
• How to respond with correct HTTP response codes
• How to handle errors
• How to manage api versions
• and many more

Client

Web API

Backend

request

response

Uniform Resource Identifiers

• A syntax or convention to identify resources in the web
• Syntax
  • URI = <scheme> "://" <authority> "/" <path> [ ? query] [# fragment]
• Example
  • http://api.acme.com/login

Resources

• Anything important enough to be referenced in its singularity
• Resource Archetypes
  • Document
  • Collection (nouns)
  • Store (client managed storage)
  • Controller - (actions, verbs)

Resource Oriented Architecture

• Addressability
• Statelessness
• Connectedness (resource relationships)
• Uniform Interface
  • Methods: GET, POST, PUT, DELETE, HEAD, OPTIONS
  • HTTP Method Headers
  • HTTP Status Codes

Addressability

• Unique
• Clearly describe the resource
• Must be discoverable
• Each URI must map to one and only resource

Statelessness

• State must not be stored in server
• Each request must provide complete context
• Simple design
• Should be evolvable
• Easy to scale
• Avoid HTTP sessions and cookies
• Must not have any side effects

Uniform Interface - HTTP Methods

• GET
• POST
• PUT
• DELETE
• HEAD
• OPTIONS

URI + HTTP Methods = REST API

• Just require two URI per resource
  • collection - /api/v1/users
  • element - /api/v1/users/id

POST - GET - PUT - DELETE

CREATE - READ - UPDATE - DELETE

GET

Fetch resource collection

GET /api/v1/users
HTTP Status : 200 OK
response headers
response

GET

Fetch single resource 

GET /api/v1/users/1211 -- /api/v1/users/{id}
HTTP Status : 200 OK
response headers
response

HEAD

Fetch single response headers

HEAD /api/v1/users/[{id}]
HTTP Status : 200 OK
response headers

POST

Create a resource

POST /api/v1/users

Request Headers

Request body

HTTP Status : 201 CREATED
response headers

response

PUT

Modify a resource

PUT /api/v1/users/{id}

Request Headers

HTTP Status : 200 OK
response headers

response

DELETE

Delete a resource

DELETE /api/v1/users/{id}

Request Headers

Request body

HTTP Status : 200 OK
response headers

Associations

How to model associations

All employees in a department

GET /api/v1/departments/{id}/employees

Get an employee in a department

GET /api/v1/departments/{id}/employees/{empId}

Good Practices

GET, HEAD should not modify resource and must not have any side effects

Never expose any unsafe operations using GET

Idempotency

GET, HEAD PUT, DELETE, OPTIONS are idempotent

POST is not

Resource Operations Beyond standard HTTP Methods

Use controller pattern - verbs in the URI

Example

/login

/logout

/resetPassword

Searching

Use Query Parameter

GET /api/v1/departments?q="{'name':'finance'}"&page=1&limit=50&order=asc

Versioning

Incorporate version in URI

POST /api/v1/departments

Optimization - Slow Changing Resources

Use HTTP Headers to reduce both client and server processing time

Response Header - ETag, Last-Modified

Request Header - If-Modified-Since, If-None-Match

Tools

API Design is a must

Spend time on proper API Design

Use tools such as Apiary, API-Blueprint, Swagger etc

Good documentation acts as contract for api consumers

Steps to create REST API

Identify Resources

Identify Resource Representational Format

Identify Supported Methods

Identify Required request, response Headers

Identify Return Status Codes

Content Negotiation

Resources can be served in different representations

XML, JSON, HTML, CSV ...

Methods

Request Header - Accept, Content-Type

Query Parameter GET /api/v1/departments?format=json

URI Extension GET /api/v1/departments.json

Testing REST API Services

Curl

frisbyjs (node)

junit

Postman

Some Antipatterns

Overusing POST
Actions in URI

Service as a resource

Server managed sessions