Introducing

RESTful  APIs

Rahul Yadav |

What's an API   ??

application programming interface is a set of subroutine definitions, protocols, and tools for building Application software

Web Services examples are SOAP , RPC , REST

REST Architecture

REpresentational State Transfer
Resource Based
Representations
Contraints :-
  • Uniform Interface
  • Stateless
  • Client - Server
  • Cacheable
  • Layered System
  • Code On Demand

 

Resource Based

  • Things vs Actions
  • Nouns vs Verbs
  • Identified by URIs ( not necessarily unique )
  • Multiple Representations

Representations

  • Manipulating Resources

  • Formats Typically JSON or XML

Example

  • Resource : plants
  • Service : Location they are found
  • Representation -:

name , country, lat ,long

Format ( Json or XML )

Uniform Interface

  • Defines the interface btw client and server
  • Decouples the architecture
  • Fundamental to RESTful Design

For Web services this means -:

  • URI ( Resource Location )
  • HTTP Verbs ( action )
  • HTTP Request and Response

Stateless

  • Server contains no client state
  • Self descriptive messages
  • All the session state is held on client

Client - Server

  • Disconnected System
  • Seperation of Concerns

Cacheable

  • Server responses ( representaions ) are cacheable
  • Implicitly
  • Explicitly
  • Negotiated

Code On Demand

  • server temporarily extend client
  • Transfer logic to client
  • Client executes logic
  • Only optional constraint 

WHY REST ?

  • Scalability
  • Generality
  • Independence
  • Caching
  • Security
  • Encapsulation
  • Poratability

Is there any Spec  ?

Unfortunately , no. But work is on going on ION spec but has not been submitted as of now .

Are todays web services truly RESTful  ?

Some of the API's come close ( But many violates one of previously mentioned constraints )

Example -:  Three - legged OAuth

Lets Explore  !!!!!

REST is easy to Use but Hard to Implement

Unless you follow some Guidelines
  • Hypermedia

  • As

  • The

  • Engine

  • Of

  • Application

  • State

HATEOAS

Fudamentals

Resources

  • Nouns not Verbs
  • Coarse grained not fine grained
  • Architectural style for use-case scalability

What if  ?

/getAccount

/getAllAccounts

/searchAccounts

/createDirectory

/createLdapDirectory

/updateGroup

/updateGroupName

/findGroupsByDirectory

/searchGroupsByName

/verifyAccountEmailAddress

/verifyAccountEmailAddressByToken

Smells like bad RPC.  DON’T DO THIS.

Keep It Simple

Lets Find a solution to this problem

Fundamentally two types of Resources :-

  • Collection Resource     /accounts
  • Instance Resource       /accounts/1234

Behaviour  / Action

  • GET = Read

  • POST  ( not obvious )

  • PUT     ( not obvious )

  • DELETE = Delete

What about complex variations ?

sweep them under the  ?
/dogs?color=red&state=running&location=park

What about Errors  ?

Media Types

  • Format Specification + Parsing Rules

  • Request: Accept header

  • Response: Content-Type header

  • application/json
  • application/ion+json
  • application/ion+json;v=2

Versioning

What About Pagination ?

/dogs?limit=25&offset=50

What about formats ?

What about non-resource-y stuff  ?

Use verbs not nouns

/convert?from=EUR&to=CNY&amount=100

Exceptional Stuff !!!!

Client Intercepts HTTP error codes !!

When client does not  all the HTTP methods ?

What about Authentication  ?

Facebook               OAuth 2.0

Twitter                    OAuth 1.0a

Google                   OAuth 2.0

(complement your api with you code SDK)

RESTFul Web Api Frameworks

Flask-RESTFul

Django REST

  • best for prototyping
  • have to add many helper extensions
  •  ​​production ready 
  • Browsable api
  • serializers
  • Testing
  • middlewares

Resources

---- Thank You---

Questions   ?

RESTFul api

By rahul yadav

RESTFul api

  • 430