Rest api standards and best practices

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

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.

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

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

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

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

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

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": "/school/api"
}

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
{
“employees": {
"canonicalLink": "/store/api/v1/employees"
},
“customers": {
"canonicalLink": "/store/api/v1/customers"
},
"capabilities": {
“cashAccepted": true,
“cardAccepted": true
},
}
Request:
GET /store/api/v1 HTTP/1.1

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
Accept: application/json
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 07:13:00 GMT
{
"id": "12",
"name": “Nutella 300g",
"price": “100",
“category“: “spreads“,
"canonicalLink": "/store/api/v1/products/12"
}
GET /store/api/v1/products/12 HTTP/1.1
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>

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
Location:
https://grocers.com:7001/store/api/v1/products/12
{
“msg”: “Product created successfully”,
"id": "12",
}
Request:
POST /store/api/v1/products HTTP/1.1
{
"price": “100",
“category“: “spreads“
}

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,
}
Request
PUT /store/api/v1/products/12 HTTP/1.1
{
"id": "12",
"price": “200",
“category“: “spreads“,
}

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,
}
PATCH /store/api/v1/products/12 HTTP/1.1
{
"price": "300",
"category": ""
}
OR
To avoid HTTP proxy issues with PATCH, use:
POST /store/api/v1/products/12 HTTP/1.1
X-HTTP-Method-Override: PATCH

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
{
"items": [{
"id": "12",
"name": “Nutella 300",
"canonicalLink": “/store/api/v1/products/12"
},{
"id": 35",
"name": “Fruit Loops",
}],
"canonicalLink": "/store/api/v1/products“
}
GET /store/api/v1/products HTTP/1.1

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
{
"items": [{
"id": “11",
"name": “Taj Mahal tea",
},{
"id": 12",
"name": “Nutella 300",
}
],
"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

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

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
{
"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

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

Rest api standards and best practices

More Related Content

What's hot (20)

Similar to Rest api standards and best practices (20)

More from Ankita Mahajan (8)

Recently uploaded (20)

Rest api standards and best practices

Editor's Notes