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. 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. |
|
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
● Mulesoft
