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

REST API – DESIGN/IMPLEMENTATION GUIDELINES

•  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

REST API - MODELING

•  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

•  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)

REST API - DESIGN

•  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

•  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

•  OTHER •  www.domainname.com/api/transfer •  Use HTTP header to communicate additional information •  Use Payload to communicate the details

REST API - Methods

•  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

•  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. •  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

REST API CONSTRAINTS

•  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

•  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

REST API VERSIONING

•  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

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