KEMBAR78
REST API Recommendations | PDF
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

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