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

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

3. 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.

4. 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.

5. 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

6. SOAP vs REST <?xml version="1.0"?<
<soap:Envelope xmlns:soap= soap:encodingStyle=
<soap:body pb=
<pb:GetUserInfo>
<pb:UserID>555</pb:UserID>
</pb:GetUserInfo>
</soap:Body>
</soap:Envelope> Vs
GET

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

8. Architectural properities
Performance
Scalability
Simplicity
Visibility
Portability

9. Example of traditional style

14. Keep the simple things simple

15. We only need two URLs per resource

16. The first is for a collection

17. /courses

18. The second is for an element

19. /courses/{id}

20. 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

21. 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

22. Verbs are bad. Nouns are good.

23. 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

24. What about associations?
GET /students/123/courses

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

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

27. Developer Message {
"developerMessage":” Message to debug the problem”,
"moreInformation": “
"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

28. 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

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

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

31. Formats
Accept: application/json
Accept: application/xml

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

33.
HTTP primer f