REST API Recommendations

REST API Recommendations

• 1.
  REST API* –DESIGN GUIDELINES & BEST PRACTICES JEELANI SHAIK, CTO@D3 BANKING * Note: REST API is also called as RESTful API
• 2.
  •  Lightweight RESTfulAPI 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.
  REST API –DESIGN/IMPLEMENTATION GUIDELINES
• 4.
  •  Drivers forREST 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.
  REST API -MODELING
• 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.
  •  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.
  REST API -DESIGN
• 9.
  •  Create adesign 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.
  •  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.
  •  OTHER •  www.domainname.com/api/transfer • Use HTTP header to communicate additional information •  Use Payload to communicate the details REST API - Methods
• 12.
  •  Stick withHTTP 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.
  •  Accept-Language: en • Accept: application/JSON REST API - Content Negotiation
• 14.
  REST API MATURITYMODEL
• 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.
  REST API CONSTRAINTS
• 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.
  •  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.
  REST API VERSIONING
• 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.
  REST API -DOCUMENTATION
• 22.
  REST API –Use a tool such as swagger for live documentation
• 23.
  REST API –Use a tool such as swagger for live documentation