Principles and Practices | Web API

This article enumerates the best principles and practices for designing, deploying, and maintaining successful Web API’s that can drive organizational innovation forward.  This document has borrowed and consolidated ideas from Apigee (Bryan Mulloy), Microsoft, and Mulesoft (Mike Stowe); I highly encourage the reader to also review these primary sources.  I will use the fictional Acme company as an example throughout this article.

 

Category	Principles and Practices
Requirements	Understand your users.  What are the use cases? What technologies/services will be used? What are the business resources that need to be managed? What are their entity relationships? Acme Answer: Users are digital Builders and the key resources are Bricks
Design Strategy	Think long-term.  Not just release 1.  But think 2-3 years ahead. Ensure the API is platform independent to maximize API portability and usage. Be stateless to maximize scalability, increase cacheability, and reduce client/server dependencies. Be consistent. Be flexible. Keep It Simple and minimize complexity throughout.
Prefer Nouns, not Verbs	Prefer plural nouns, instead of verbs. http://acme.com/api/bricks [preferred] vs. http://acme.com/api/getbricks [avoid, since this is more verbose and leads to complexity] Use verbs if you are implementing calculations or transformations that are unrelated to resources.
Map CRUD to HTTP verbs	DELETE, GET, PUT, and POST requests should be idempotent. http://acme.com/api/bricks Create => POST Read => GET Update => PUT Delete => DELETE
Map Errors to HTTP Status	Handle errors consistently, at least 5 of the 70-ish HTTP response status codes. 200 - OK 400 - Bad Client Request Format 401 - Unauthorized Client Request 404 - No Resource 500 - Server Error 501 - Not Implemented 503 - Service Unavailable Map exception and detailed error messages into the response payload.
Version API	Never release the API without a version.  This is part of managing change and being flexible. Prefer versioning in the base URI to be explicit instead of a request query or header parameter. Prefer simple ordinal numbers over dot notation and timestamping. Prefer v1 instead of v1.0 or v2016-01-01. http://acme.com/api/v1/bricks
IO Formats	Default format for input and output should be JSON. Support multiple input and output formats. Optionally support XML for input and output as well CSV for output.   Support content types specified in the URI: GET /api/v1/bricks.json GET /api/v1/bricks.xml   Support content types specified in request header: Content-Type: application/json
Collection Navigation	Provider filtering, sorting, field selection, and pagination of collections. GET /api/v1/bricks/?color=red GET /api/v1/bricks/?sort=model GET /api/v1/bricks/?limit=50&offset=10 GET /api/v1/bricks/?fields=id,model,color
Consolidate	Consolidate all API services and requests into one domain. Example: http://api.acme.com/v1/
Document	Document your API and publish the specification online.  Use Swagger or RAML.
Security	Authenticate and authorize all users. Validate input requests. Prefer declarative security on individual methods of service endpoints. For private intranets using Active Directory, assign permissions to roles consisting of AD groups. For public extranets, consider using OAuth 2 and SSL. Throttle users that exceed API limits and generate 503 errors with Retry-After headers.
Deploy	Log requests for troubleshooting and customer metering. Support multiple channels for customer feedback: email list, online forum, Slack channel, etc. Monitor API health, activity, and usage in Production. Consider using 3rd party products for enterprise API management and standardization.

 

References

●       Apigee

●       Microsoft

●       Mulesoft

●       Rest Cookbook

●       Mathieu Fenniak Checklist

Book Summary | Scalability Rules

This article is a reboot of my blog.  Posts will consist of book reviews, informal musings on economics, history, and software, as well as more formal, didactic articles on technology.

Here is a book summary and review of Scalability Rules by Abbott and Fisher.  Practical.  Concise.  Packed with good advice on design, infrastructure, and organizational processes.  The latest edition includes stories that give context to the rules.  Highly recommended.

Category	Rule
Design	Do not over engineer the solution. Design scale into solutions: design @ 20X, implement @ 3X, deploy @ 2X Avoid single point of failure. Avoid sequencing components and systems in synchronous series. Strive for statelessness.  Watch out for server affinity. Communicate asynchronously as much as possible (prefer pub-sub to RPC). Design your application to be monitored.
Reduce	Reduce object usage including DB, DNS, sockets, images, CPU, MEM, DISK, etc
Cache	Cache static, infrequently changing information and objects appropriately. Use web page cache, image cache, application reference data cache, etc.
Scale	Design to clone things on commodity hardware and network load balancer. Design to split different and similar things. Design your solution to scale out.  Use AKF scale cube. Scale out your data centers. Design to leverage the cloud, but be wary of scaling through 3rd party.  Details matter.
Platform	Use database appropriately.  Need ACID (Atomic, Consistent, Isolated, Durable)? Use firewalls appropriately. Use log files actively. Do not double check your work… do not re-read your data after write. Stop redirecting traffic. Leverage Content Distribution Networks (CDN). Use expire headers in HTTP requests to reduce duplicates for static data. Purge, archive, and cost justify storage.
Process	Test.  Measure.  Rinse.  Repeat. Learn aggressively and especially from failure through team discussion. Do not rely on QA to find mistakes. Design for rollback of code. Be aware of costly relationships and dependencies (networks, databases, etc).
Database	Understand object relationships. Use the correct database lock. Avoid multi-phase commit. Avoid select for update. Avoid select *. Separate business intelligence from transaction processing.
General	Do not do anything more than once. Do not do anything that is unnecessary. Get as much as in one request as possible.