Rest api standards and best practices
Download as PPSX, PDF11 likes7,889 views
This presentation outlines best practices for developing RESTful web services over HTTP, focusing on naming conventions, URI structure, API versioning, error handling, and response standards. It emphasizes the importance of standard HTTP methods (GET, POST, PUT, DELETE) for CRUD operations and provides guidelines for resource representation and interaction. Key topics include response status codes, managing resources, and ensuring clear communication with clients about resource availability and errors.
![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](https://image.slidesharecdn.com/restapistandardsandbestpractices-160619181341/85/Rest-api-standards-and-best-practices-7-320.jpg)
![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"
}](https://image.slidesharecdn.com/restapistandardsandbestpractices-160619181341/85/Rest-api-standards-and-best-practices-8-320.jpg)
![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](https://image.slidesharecdn.com/restapistandardsandbestpractices-160619181341/85/Rest-api-standards-and-best-practices-13-320.jpg)
![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](https://image.slidesharecdn.com/restapistandardsandbestpractices-160619181341/85/Rest-api-standards-and-best-practices-14-320.jpg)
![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](https://image.slidesharecdn.com/restapistandardsandbestpractices-160619181341/85/Rest-api-standards-and-best-practices-15-320.jpg)
Rest api standards and best practices
- 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