Ashish Pandit IT Architect, Middleware & Integration Services RESTful API Design Ashish Pandit IT Architect, Middleware & Integration Services

Agenda What is RESTful API SOAP vs REST RESTful API Design guidelines Q&A

RESTful API  REST is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system.

SOAP vs REST SOAP - SOAP brings it’s own protocol and focuses on exposing pieces of application logic (not data) as services. SOAP exposes operations. SOAP is focused on accessing named operations, each implement some business logic through different interfaces. REST - RESTs sweet spot is when you are exposing a public API over the internet to handle CRUD operations on data. REST is focused on accessing named resources through a single consistent interface.

SOAP vs REST REST SOAP Data format Supports many data formats e.g. JSON, csv, binary etc Supports xml format Transport Supports http(s) Supports many transports e.g. http(s), SMTP, JMS, ftp Best fit for web clients, mobile applications, multi-channel applications Integration usecases Fine grain security When formal contract is required better performance and scalability Can’t be cached Strength Simplicity, uniform style WS-Security, WS-Atomic transaction, WS-Reliable messaging State information Stateless Supports stateful operation and conversation Aligns with Resource view Method view

SOAP vs REST <?xml version="1.0"?< <soap:Envelope xmlns:soap=www.example.net/resources/soapenvelope soap:encodingStyle=www.example.net/resources/soapencoding> <soap:body pb=www.example.net/resources/userdatabase> <pb:GetUserInfo> <pb:UserID>555</pb:UserID> </pb:GetUserInfo> </soap:Body> </soap:Envelope> Vs GET www.example.net/users/555

REST – Architectural constraints Client-Server Stateless Cacheable Layered system Uniform interface

Architectural properities Performance Scalability Simplicity Visibility Portability

Example of traditional style

Keep the simple things simple

We only need two URLs per resource

The first is for a collection

/courses

The second is for an element

/courses/{id}

HTTP Verbs Resource POST Create GET Read PUT Update DELETE Delete /courses Create a new course List all the courses Delete all courses /courses/1234 Error Show course detail If exist, update the course Delete the course

HTTP Verbs Resource POST Create GET Read PUT Update DELETE Delete Safe – side effect No Yes Idempotent – can be invoked repeatedly without changing the state

Verbs are bad. Nouns are good.

How to Identify Resources? Analyze your use cases to find domain names that can be operated using create, read, update or delete Use resource granularity appropriately e.g. person vs student Exceptions use cases - when it comes to computing e.g find distance between 2 points, promote etc. Use GET

What about associations? GET /students/123/courses

What about complex variations? Sweep variations under the ‘?’ E.g. /students?term=FA15&status=valid&college=engineering

Response Code 1xx – Hold on 2xx – Here you go 3xx – Go away 4xx – You (Client) messed up 5xx – I (Server) messed up

Developer Message { "developerMessage":” Message to debug the problem”, "moreInformation": “http://link.to.additional.information”, "errors”:[ {"message”: "All deadlines for the term you selected have” }], "status":” Describe the error message over and above http code”, "message":" User friendly message” }   Operation HTTP Verb Recommendation Response Update a resource PUT Need id in order to submit the request Idempotent and not safe (has side effect) operation Not necessary to return a link via a Location header 200 (OK), with data 204 (NO CONTENT)  Creation of new resource POST Not idempotent and not safe 201 upon successful creation, returning a Location header with a link to the newly created resource You can send the resource body back in response back. You can use alternate attribute (?_body=false) to change the behavior  Read Get Idempotent and safe operation 200 (OK), with data  200 (OK) with empty list - if response is supposed to return collection and has empty data set  404 when specific resource doesn't exist Deleting a resource Delete Idempotent and not safe operation   204 (NO CONTENT)  404 (NOT FOUND) when calling DELETE on a resource a second time

Operation HTTP Verb Recommendation Response Update a resource PUT Need id in order to submit the request Idempotent and not safe (has side effect) operation Not necessary to return a link via a Location header 200 (OK), with data 204 (NO CONTENT)  Creation of new resource POST Not idempotent and not safe 201 upon successful creation 202 Request accepted   Read Get Idempotent and safe operation 200 (OK), with data  200 (OK) with empty list - if response is supposed to return collection and has empty data set  404 when specific resource doesn't exist Deleting a resource Delete Idempotent and not safe operation 204 (NO CONTENT)  404 (NOT FOUND) when calling DELETE on a resource a second time

What about versioning? https://api.ucsd.edu/v1/students Only version for breaking changes Only version when necessary

Pagination courses/search?termCode=FA15&pageSize=3&pageNumber=1

Formats Accept: application/json Accept: application/xml

Q & A API Security will be covered at a later point

https://www.youtube.com/watch?v=hdSrT4yjS1g HTTP primer http://www.ietf.org/rfc/rfc2616.txt http://www.slideshare.net/restlet/the-neverending-rest-api-design-debate https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pd f https://collab.ucsd.edu/display/DEV/REST+API+Guidelines