Anti-patterns of Web API’s

Bishr Tabbaa
ITNEXT
Published in
6 min readJan 13, 2018

--

Web API’s are request-response message services that run on HTTP servers (e.g. IIS, Apache, Nginx). Web API’s started as informal client/server RPC-style interfaces in the 1990’s, then evolved to more structured SOAP-styled, XML-centric services (2000’s) and more recently settled onto RESTful services using JSON that have become the defacto standard for delivering enterprise information services over the Internet and inside company intranets. I have been designing, developing, and delivering Web API’s for different businesses across multiple industries in the last ten years, and wanted to share some of the most important anti-patterns, mistakes, and bad habits that I have observed and learned about from other practitioners so that you can avoid them and thereby help your organizations deliver great software and competitive advantage in the marketplace. Enjoy and let me know what you think!

  1. Not REST — I am not a strict RESTafarian, but acknowledge that pragmatic REST is right about several things.
  • First Things, First — If you expose operations at the top, then you will have API bloat due to the combinatorics of operation X object and this results in higher maintenance costs; instead, follow the dictum of being resource-centric with objects as first class citizens and offering a handful of child operations related to their parent objects.
  • GET it, got it. — REST also standardizes the HTTP verbs and idioms for invoking your object’s operations; these conventions will simplify the number of design decisions you make and also make it easier for customers to learn your API. Use GET to get data. Use PUT/POST to change data. Use DELETE to delete data.
  • What’s the Status? — 200 is Good, and 500 is Bad. That’s enough, right? Wrong. What about bad input formats? Unauthorized users? Objects not found? Service quota limits exceeded? Without consistent HTTP status codes, your customers will not know the difference between success or failure without parsing the response body. Use a few status codes well, and they will appreciate it.
  • Mini MIME — If there is neither support for multiple MIME types for I/O, nor use of standard header parameters, then it decreases your API audience and chances of success. Support JSON for I/O as a must and minimum; consider CSV as a go-to for data integration with external, legacy systems, and contemplate XML as an optional I/O format.

2. No Versioning — Things change, and so will your API. If you do not do this, then your customers will at the least, hate you and wish terrible things to befall you when the API is updated without backwards compatibility and at worst, consider switching to alternatives. There are different versioning approaches ranging from URI to request query/header parameters; understand the tradeoffs and choose one. Just pick one and stick with it. As an aside, I do prefer the URI (e.g. “api/v1/MyResource”) because it makes it clear to the customer what version is being used.

3. No Documentation — Whether the documentation is a simple wiki with how to’s and examples (try mkdocs), an interactive API browser based on Swagger or RAML attributes decorating your endpoints, or a combination of both (better), your direct customers are developers and you should assist them in learning and using your services.

  • 0-to-60: Developers should be able to get from 0-to-60 and beyond “Hello World” as soon as possible; include quick start tutorials and fast 1–2–3 signups to streamline this process.
  • Q&A: Make sure the documentation is accurate, clear, complete, regularly updated, and searchable. If you don’t check this easy box, then you will be answering the same painful questions from users over and over again.

4. No Security — Security is front page news. It is existential, strategic, and should be one of your first API design considerations. You do not want to be the IT architect, CTO, or CEO explaining to the board or journalists why you got hacked, exposed confidential data, or allowed unauthorized changes to important data.

  • No Authentication/Authorization — you must know who the API clients are and what the users (e.g. sometimes people, sometimes machines) are allowed to do. Whether it’s NTLM for Windows/AD-based private intranets or OAuth for public extranets, pick something for the short-term and plan for the long-term future.
  • No Input ValidationOWASP’s Top Vulnerabilities highlights multiple security vulnerabilities such as SQL/OS injection and cross site scripting. Use a secure parser when validating requests.
  • No Error Handling — Make sure you handle errors and exceptions securely and do not reveal system internals in stack traces and status messages to external users.

5. No Scalability — If you do not design for scalability and do not plan for additional capacity buffers, then you may become a victim of your API’s success. More details on this subject can be found in a dedicated article on the subject.

  • Hello Dolly: Design your service so that it can be cloned horizontally faster than a genetically engineered sheep in the lab. Strive for statelessness and watch out for affinity to servers. Check out of the AKF Scale Cube for a multi-dimensional view on performance.
  • Redundancy: Avoid single points of failure like a noose around the neck.
  • Caching: Yes, you may need to cache some long-lived, little changed, frequently used objects from persistent storage into memory, but if you cache too much (e.g. sticky sessions with users) that changes too often, then you may not be able to scale horizontally and load balance across multiple nodes. Be as stateless as possible, but no more.
  • Drink ACID at your own Risk: Do you really need consistency and serializability? What other data constraints can you relax?

6. No Logs — Monitor and log API activity across multiple nodes. Without good logs, its difficult to troubleshoot, plan for capacity changes, and follow up with customers regarding their usage. Start with text-based log files readable by man and machine. Consolidate the files for service-wide reporting using UNIX syslog or file watchers. Consider streaming the logs real-time into a dedicated service (e.g. Azure Application Insights, Amazon Cloud Watch, Splunk, Elasticsearch).

7. Not Fair — If you don’t have the ability to throttle customers, then you are vulnerable to Denial of Service attacks and will not be able to fairly service most other customers. For fellow .NET engineers, I recommend the WebApiThrottle project by Stefan Prodan; it offers the ability to throttle by IP address, client identity, and endpoint, is configurable by policy documents, can white list by network address or client, can be customized, and it’s easy to integrate into ASP.NET solutions. Both AWS and Azure also offer world-class API gateway management services with similar feature sets. Measure first, set conservative limits as a start, publish the limits to customers on the API wiki, monitor usage, and manage traffic rate limits flexibly based on your infrastructure capacity (supply) and customer needs (demand).

8. No Customer Service — It’s all about keeping customers happy in the end. Inform users about upcoming releases. Fulfill SLA’s. Fix bugs and implement features fast; deliver them to Production faster. Publish release notes of past changes and the future roadmap. Facilitate online chat forums where you can help them, and they can also help each other. Schedule meetings with the most important stakeholders on regular basis. Send your customers surveys,and ask good questions about what they like/dislike and what they want to see going forward. The answers might surprise you.

Web API Anti-Patterns

Enjoy the article? Follow me on Medium and Twitter for more updates.

References

--

--

Architect @awscloud • Data Scientist • Author • Board Director • AWS • Complexity & Data Science • History of System Failure • AIML • @RiceAlumni • 🎾☁️🖥️🧮