Rest api standards and best practices

Rest api standards and best practices

• 1.
  REST WEB SERVICEDEVELOPMENT GUIDELINES AND BEST PRACTICES PRESENTED BY: ANKITA MAHAJAN
• 2.
  OBJECTIVE This presentation givesan 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 URICONVENTIONS 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: HTTPmethods • 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 • SEMANTICALLYPRECISE • 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 • Collectionresource: /[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 • Clientsshould 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 • Alist 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 SINGULARRESOURCE • 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 SINGULARRESOURCE • 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 stylesand 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