Download - REST API Recommendations
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
• 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
• 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)
• 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
• 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
• 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
• 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