REST web service development guidelines and best practices. An introduction to guidelines and best practices for developing REST API or web services.

1. REST WEB SERVICE DEVELOPMENT
GUIDELINES AND BEST PRACTICES
PRESENTED BY:
ANKITA MAHAJAN

2. OBJECTIVE
This presentation gives an overview of best practices and
guidelines for creating a rest service or for developing a rest
service framework, over HTTP.
These conventions are also helpful for rest services consumers.

3. NAMING AND URI CONVENTIONS
API VERSIONING AND CATALOG
COLLECTION RESOURCE
ERROR RESPONSE ENTITY
REFERENCES
INTRODUCTION
A
G
E
N
D
A
RESPONSE STATUS CODES
SINGULAR RESOURCE

4. INTRODUCTION
REST
Constraints
Client-Server
Stateless
Cacheable
Uniform
Interface
Layered
System
Code on
Demand
(optional)
• REST: Representational State Transfer
• REST CONSTRAINTS
• BASIC TERMINOLOGY:
• Resource
• Collection
• Instance/Singular
• REST API or service
• Resource Identifier
• Root resource
• Sub-resource

5. BEHAVIOR
• Behavior: HTTP methods
• GET
• POST
• PUT
• DELETE
• HEAD
• PATCH
• Behavior should be implemented based on CRUD, unless there’s a specific
requirement otherwise.
• Coarse-grained approach for data
• Media type or Data format of response: Client should be able to parse
response
• application/json
• application/xml

6. NAMING CONVENTIONS
• SEMANTICALLY PRECISE
• LOWER CAMEL CASE
• SHOULD NOT CONTAIN:
 UNDERSCORES
 HYPHENS
 NUMBERS
• Date/Time: UTC should be used, following ISO:8601 date/time standard
• Collection resource names should be PLURAL NOUNS (not verbs)
• Ex)
/service/api/v1/departments/12/shelves/34/products

7. RESOURCE URI
• Collection resource: /[context/]version/resourceName
• Ex: /store/api/1.2/employees
• Singular resource: /[context/]version/resourceName/resourceId
• Ex: /store/api/1.2/employees/2
• Child resource: rootResourceUri/childResourceName
• Ex: /store/api/1.2/employees/2/feedbacks
• Query Parameters: /resourceName?queryParam1=val1&queryParam2=val
• Ex: /store/api/1.2/employees?department=20&experience=5

8. API VERSIONING
• Clients should know desired version no.
• Multiple API versions can exist
simultaneously.
• It should be possible to find out
current/latest version
GET /store/api HTTP/1.1
Host: grocers.com:7001
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
Content-Type: application/json
{
[
"v1": {
"canonicalLink": "/store/api/v1"
},
"v2": {
"canonicalLink": "/store/api/v2"
}
],
"canonicalLink": "/school/api"
}

9. RESOURCE INDEX/CATALOG
• A list of all resources available in the API.
• Must include all root resources.
• Separate catalog for each version. Response:
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
Content-Type: application/json
{
“employees": {
"canonicalLink": "/store/api/v1/employees"
},
“customers": {
"canonicalLink": "/store/api/v1/customers"
},
"capabilities": {
“cashAccepted": true,
“cardAccepted": true
},
"canonicalLink": "/store/api/v1"
}
Request:
GET /store/api/v1 HTTP/1.1
Host: grocers.com:7001

10. GET SINGULAR RESOURCE
• Use GET HTTP method to fetch response, based on accept header.
• Accept header: application/JSON or application/XML
GET /store/api/v1/products/12 HTTP/1.1
Host: grocers.com:7001
Accept: application/json
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
Content-Type: application/json
{
"id": "12",
"name": “Nutella 300g",
"price": “100",
“category“: “spreads“,
"canonicalLink": "/store/api/v1/products/12"
}
GET /store/api/v1/products/12 HTTP/1.1
Host: grocers.com:7001
Accept: application/xml
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<resource>
<id>12</id>
<name>Nutella 300g</name>
<price>100</price>
<category>spreads</category>
<canonicalLink>/store/api/v1/products/12</can
onicalLink>
</resource>

11. CREATE SINGULAR RESOURCE
• Use POST HTTP method targeting a collection resource URL.
• Response MUST contain new resource’s URI in Location response
header.
• Response MAY contain the following in response body :
• The newly created resource
• A generic acknowledgement with entity id and/or URL of the new resource
Response:
HTTP/1.1 201 Created
Date: Thu, 26 May 2016 07:13:00 GMT
Content-Type: application/json
Location:
https://grocers.com:7001/store/api/v1/products/12
{
“msg”: “Product created successfully”,
"id": "12",
"canonicalLink": "/store/api/v1/products/12"
}
Request:
POST /store/api/v1/products HTTP/1.1
Host: grocers.com:7001
Content-Type: application/json
{
"name": “Nutella 300g",
"price": “100",
“category“: “spreads“
}

12. FULL UPDATE SINGULAR RESOURCE
• Use PUT method targeting the singular resource, for “full” update
• As per HTTP specification, the full resource representation should be
provided in the PUT request body
• Read-only fields like “id” and “canonicalLink” in request body should
be ignored by API
Response
HTTP/1.1 204 No content
Date: Thu, 26 May 2016 07:13:00 GMT
OR
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
{
“msg”: “Product updated”,
“id”:12,
"canonicalLink": "/store/api/v1/products/12"
}
Request
PUT /store/api/v1/products/12 HTTP/1.1
Host: grocers.com:7001
Content-Type: application/json
{
"id": "12",
"name": “Nutella 300g",
"price": “200",
“category“: “spreads“,
"canonicalLink": "/store/api/v1/products/12"
}

13. PARTIAL UPDATE SINGULAR RESOURCE
• Use PATCH method along with a “patch document”
• Service SHOULD allow client to update only required attributes of a
resource
• Patch-document specification:
• XML Patch [RFC5261]
• JSON Patch (draft-ietf-appsawg-json-patch)
HTTP/1.1 204 No content
Date: Thu, 26 May 2016 07:13:00 GMT
OR
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
{
“msg”: “Product price and category updated”,
“id”:12,
"canonicalLink": "/store/api/v1/products/12"
}
PATCH /store/api/v1/products/12 HTTP/1.1
Host: grocers.com:7001
{
"price": "300",
"category": ""
}
OR
To avoid HTTP proxy issues with PATCH, use:
POST /store/api/v1/products/12 HTTP/1.1
Host: grocers.com:7001
X-HTTP-Method-Override: PATCH

14. GET COLLECTION RESOURCE
• API MUST return all default attributes of child resources along with
their canonical links.
• Based on performance or scalability requirements, paging and/or
filtering MAY be supported to return a subset of child resources.
HTTP/1.1 200 OK
Date: Fri, 03 June 2016 07:32:00 GMT
Content-Type: application/json
{
"items": [{
"id": "12",
"name": “Nutella 300",
"canonicalLink": “/store/api/v1/products/12"
},{
"id": 35",
"name": “Fruit Loops",
"canonicalLink": “/store/api/v1/products/35"
}],
"canonicalLink": "/store/api/v1/products“
}
GET /store/api/v1/products HTTP/1.1
Host: grocers.com:7001
Accept: application/json

15. COLLECTION RESOURCE PAGING
• Paging is used to retrieve a subset of collection items based on two request
query parameters: offset and limit
• To get the next/previous page, query the next/previous link
• hasMore specifies if there are subsequent elements to be retrieved
HTTP/1.1 200 OK
Date: Fri, 03 June 2016 07:32:00 GMT
Content-Type: application/json
{
"items": [{
"id": “11",
"name": “Taj Mahal tea",
"canonicalLink": “/store/api/v1/products/11"
},{
"id": 12",
"name": “Nutella 300",
"canonicalLink": “/store/api/v1/products/12"
}
],
"hasMore": true,
"canonicalLink": "/store/api/v1/products",
"selfLink": "/store/api/v1/products?offset=10&limit=2",
"previousLink": "/store/api/v1/products?offset=8&limit=2",
"nextLink": "/store/api/v1/products?offset=12&limit=2"
}
GET
/store/api/v1/products?offset=10&
limit=2 HTTP/1.1
Host: grocers.com:7001
Accept: application/json

16. RESPONSE STATUS CODES
• Each HTTP response contains a status code which signifies the result of
the HTTP request. The following should be supported:
• 200: OK. Response for successful GET, PATCH, PUT, DELETE
• 201: Created. Response for successful POST
• 204: No Content. Request successfully executed & response doesn't have
content
• 400: Bad Request. Invalid parameters, parameter values or data format
• 404: Resource not found. Invalid URL/resource
• 500: Internal server error
• The entire list of HTTP status codes can be found on httpStatuses.com

17. RESPONSE ERROR ENTITY
• In case of a any error or validation failure a special response should be
used.
• An error entity should only have descriptive error details relevant for
client.
• Response should never have stack trace, internal code or file paths.
HTTP/1.1 400 Bad Request
Date: Mon, 10 Jun 2016 11:32:12 GMT
Content-Type: application/json
{
"httpStatusCode": 400,
"httpMessage": "Bad Request ",
“errorTitle":”Invalid instance id”
"errorCode": "errorcode:invalid:id",
"errorDetail": “The requested product does not exist“,
“moreInfo “: “http://www.grocers.com/errors/400/product"
}
GET /store/api/v1/products/6000
HTTP/1.1
Host: grocers.com:7001
Accept: application/json

18. REFERENCES
• Architectural styles and the design of network-based software
architectures, PhD Dissertation, Thomas Fielding,
http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation
.pdf

19. THANK YOU