Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
REST API* – DESIGN GUIDELINES & BEST
PRACTICES
JEELANI SHAIK, CTO@D3 BANKING
* Note: REST API is also called as RESTful API
•  Lightweight RESTful API is preferred over SOAP web services API
•  Lightweight JSON format is preferred over XML format...
REST API – DESIGN/IMPLEMENTATION
GUIDELINES
•  Drivers for REST API
•  Growth of Single Page Applications (SPAs) within browsers that require
coarse grained and granu...
REST API - MODELING
•  Top-down (Preferred)
•  Use case driven
•  Business team’s input
•  Future needs
•  Bottom-up
•  Focused on exposing th...
•  Identify Participants
•  Internal stakeholders
•  External stakeholders
•  Admins
•  Other Applications
•  Devices
•  I...
REST API - DESIGN
•  Create a design norms document
•  Encoding and formats
•  Uniform Interface
•  HTTP Headers, Methods and Response codes...
•  GET – To fetch the representation of a business entity (User) or a
collection of business entities (Accounts). Two cons...
•  OTHER
•  www.domainname.com/api/transfer
•  Use HTTP header to communicate additional information
•  Use Payload to com...
•  Stick with HTTP Standard response codes
•  Informational (1xx) - Communicates transfer protocol-level information
•  Su...
•  Accept-Language: en
•  Accept: application/JSON
REST API - Content Negotiation
REST API MATURITY MODEL
•  Level 0: “The Swamp of Plain Old XML (POX)”
•  Use HTTP as the transport system
•  Single API Endpoint for all requests...
REST API CONSTRAINTS
•  Client / Server
•  Design the API to be consumed in a client/server architecture
•  Client and server should be able to...
•  Uniform Interface
•  Business entities can be consumed and manifested using a set of well defined URI
endpoints
•  Uses...
REST API VERSIONING
•  Versioning values
•  Using Date
•  Example: Twilio, https://api.twilio.com/2010-04-01/Accounts
•  Using Version number
...
REST API - DOCUMENTATION
REST API – Use a tool such as swagger for live documentation
REST API – Use a tool such as swagger for live documentation
Upcoming SlideShare
Loading in …5
×

REST API Recommendations

282 views

Published on

  • Login to see the comments

  • Be the first to like this

REST API Recommendations

  1. 1. REST API* – DESIGN GUIDELINES & BEST PRACTICES JEELANI SHAIK, CTO@D3 BANKING * Note: REST API is also called as RESTful API
  2. 2. •  Lightweight RESTful API is preferred over SOAP web services API •  Lightweight JSON format is preferred over XML format for Payload •  The API should be stateless •  Secure the transport using SSL standards (TLS 1.2) •  Build the API using the proper use of HTTP Verbs and consistent naming conventions •  Use HTTP status coders or response codes are used to indicate the status of the request •  Keep data structures of payload consistent over different operations for the same type of data. Example: GET should return the same data that can be sent in a POST request •  Data consumed and returned by the API should be handled using a modern framework, not via manual string manipulation & concatenation, XPATH queries or other unreliable methods •  Comprehensive documentation for all data types and API methods, as well as sample request and responses. RESTful API – Overview Summary
  3. 3. REST API – DESIGN/IMPLEMENTATION GUIDELINES
  4. 4. •  Drivers for REST API •  Growth of Single Page Applications (SPAs) within browsers that require coarse grained and granular access to data •  Growth of multi device applications and the need to support Omni- channels •  Lightweight and API-first approach •  REST API Phases •  Modeling •  Design •  Development •  Validation Overview
  5. 5. REST API - MODELING
  6. 6. •  Top-down (Preferred) •  Use case driven •  Business team’s input •  Future needs •  Bottom-up •  Focused on exposing the data •  Focus is on exposing/providing access to data REST API Modeling – Top-down vs. bottom-up
  7. 7. •  Identify Participants •  Internal stakeholders •  External stakeholders •  Admins •  Other Applications •  Devices •  Identity activities and drivers •  UI Driven/Process Driven/Application Driven •  Grouping features •  User enrollment •  Core Data – Accounts, Transactions •  Breakdown activities in to steps •  Define API •  Validate API by using scenarios to test and the completeness of the API REST API - Modeling (Top-down)
  8. 8. REST API - DESIGN
  9. 9. •  Create a design norms document •  Encoding and formats •  Uniform Interface •  HTTP Headers, Methods and Response codes •  URL Naming conventions •  Metadata •  Decide on payload format type: JSON (Preferred) or XML •  Pick one to begin with •  Security & Compliance requirements •  Authentication •  Authorization •  Audit requirements REST API - Design
  10. 10. •  GET – To fetch the representation of a business entity (User) or a collection of business entities (Accounts). Two consecutive GETs should always provide the same result (Idempotent) •  POST – To create a new entity (Goal) or to perform/execute non-CRUD operations such as transfer money, schedule payments and perform comprehensive search operations •  PUT – To update an existing business entity (Transaction – adding a memo description) •  DELETE – To delete an existing entity (Budget) REST API - Methods
  11. 11. •  OTHER •  www.domainname.com/api/transfer •  Use HTTP header to communicate additional information •  Use Payload to communicate the details REST API - Methods
  12. 12. •  Stick with HTTP Standard response codes •  Informational (1xx) - Communicates transfer protocol-level information •  Success (2xx) - Indicates that the client’s request was accepted successfully •  Redirection (3xx) - Indicates that the client must take some additional action in order to complete their request •  Client Error (4xx) - This category of error status codes indicates problems on client side •  Server Error (5xx) - The server takes responsibility for these error status codes •  Do not use “200 OK” as the default standard response •  Do not create new response codes or change the meaning of the standard HTTP response codes. REST API - Response Codes
  13. 13. •  Accept-Language: en •  Accept: application/JSON REST API - Content Negotiation
  14. 14. REST API MATURITY MODEL
  15. 15. •  Level 0: “The Swamp of Plain Old XML (POX)” •  Use HTTP as the transport system •  Single API Endpoint for all requests. •  Name of the action is in the parameter or in the payload. •  Mostly POST requests. XML is the popular choice for payload format. •  Single URI, Single Verb, and No Links (SOAP, XML-RPC) •  Level 1: Resources •  Level 0 + Many URIs, Single Verb, and No Links •  Handles complexity by breaking a large service into multiple resources •  Level 2: HTTP Verbs & Response Codes •  Introduces standard set of verbs - GET/POST/PUT/DELETE •  Uses HTTP Response Codes (Series 100, 200 ,300, 400 and 500) •  Many URIs, Many Verbs, and No Links •  Level 3: Hypermedia Controls (HATEOAS) •  Many URIs, Many Verbs, and Links •  <link rel = “/accounts/1234” url = “/transactions/” /> •  Introduces discoverability – making the API self-documenting Leonard Richardson’s Maturity Model
  16. 16. REST API CONSTRAINTS
  17. 17. •  Client / Server •  Design the API to be consumed in a client/server architecture •  Client and server should be able to evolve independently •  Stateless •  Design the API to be stateless •  Not dependent upon the sequence/order or API calls •  Handles complexity by breaking a large service into multiple resources •  Fault tolerant and horizontally scalable •  Caching (ETag, Cache-Control, Expires etc.) •  Reduce bandwidth •  Reduce the number of network hops to retrieve a resource •  Resulting in less network traffic and conservation of bandwidth •  Reduce latency •  As number of network hops goes down so is latency •  Reduce load on servers •  No need to request the origin server for resource •  Reduce impact of network failures •  Cached data (including fresh and stale) can be used when network is not reachable or the origin server is unavailable REST API Constraints
  18. 18. •  Uniform Interface •  Business entities can be consumed and manifested using a set of well defined URI endpoints •  Uses HTTP methods and response codes •  Layered System •  Hide complexity •  The backend layered system is not visible or exposed to the API consumer •  Code on Demand •  Extend the behavior of the consumer of the RESTful services by providing executable code. •  In a browser context, JavaScript code can be provided to enhance UI experience REST Constraints
  19. 19. REST API VERSIONING
  20. 20. •  Versioning values •  Using Date •  Example: Twilio, https://api.twilio.com/2010-04-01/Accounts •  Using Version number •  Example: SendGrid, https://api.sendgrid.com/v3/suppression/bounces •  Versioning Schemes •  URI Component •  Version is passed as part of the URI •  /v2/accounts •  HTTP Header •  Version is communicated using a custom HTTP header •  Example: x-FI-version:v2 •  Query Parameter •  Version is communicated using a custom query parameter •  Example: /accounts?FI-version:v2 REST API Versioning
  21. 21. REST API - DOCUMENTATION
  22. 22. REST API – Use a tool such as swagger for live documentation
  23. 23. REST API – Use a tool such as swagger for live documentation

×