Collection: Web API Best Practices

July 10th, 2019

It seems like the wild, wild West out there when it comes to APIs. In this new collection, I focus on best practices when consuming and creating Web APIs.

In every position over the past five years, I've been writing and rewriting Web APIs for a number of companies and clients.

While everyone is building APIs, some developers write APIs like it's the wild west.

Using either WebRequest or HttpWebRequest to make API calls isn't a bad thing, but I prefer a little more control over my API calls.

Microsoft made it easier to write and consume APIs similar to Legos. They gave developers a core HttpClient class and added components onto it instead of replacing it yet again with another class.

The WebRequest/HttpWebRequest became the more robust HttpClient class since .NET Framework 4.5.

Since the HTTP calls over the years evolved from basic HTML calls to OAuth and other protocols, it's been hard to determine what the best practices were for writing Web APIs. 

This has been a sticky point for me over the years as well.

Why do we need API standards?

For those who feel like APIs are a simple concept, let me explain through a story earlier this year.

At the beginning of the year, I went to Codemash and decided to go to a precompiler session called "Best Practices for Robust API development in ASP.NET Core, Part 1 & 2."

What I didn't realize was the amount of technology included with APIs nowadays.

I won't go into the details (jump to the link to see the review), but it was eight hours creating a baseline ASP.NET Core 2.2 API with ALL of the trimmings. Consider it like a checklist of technologies to pick-and-choose when building an API.

Don't believe me? Check the GitHub Repo.

While this was a walk-through of how to set up an API, I can guarantee you, developers who haven't gone through an explanation at this depth would write something a little thin and miss the details when it came to standard API development.

Heck, I learned a number of new techniques during this session.

I guess my point is everyone has a way to write an API, but it shouldn't be so far-fetched that developers don't understand the code.

Luckily, we have the Internet to help out with some standards.

Using HttpClient

You're using HttpClient Wrong and It's Destabilizing your Software
The ASP.NET Monsters are at it again. Simon Timms reports on his findings from a furious client. After noticing sluggish performance, he explains why you SHOULD NOT instantiate a new instance of HttpClient. It was meant to be a singleton. His report explains what happens behind the scenes when you create an instance for every API call. Spoiler: It's not pretty.

Using IHttpClientFactory for HttpClient Requests
Directly from the source, Microsoft explains why it's better to use the IHttpClientFactory instead of instantiating HttpClient every time.

Personally, these ASP.NET Core examples are why I found out additional ways to call APIs through C#. I would rather dependency inject the IHttpClientFactory into a constructor and say "Hey, I need an HttpClient, hand one over!" instead of new-ing one up and causing performance issues.

Best Practices and Standards for APIs

Microsoft REST API Guidelines
Who better to give you good advice on how to write an API than the source who wrote C#? This Github repository is a "best practices" guide to assist with building all things API-related. One of my favorite bookmarks from Microsoft's GitHub repo.

Specification Proposal for APIs
While this specification looks like a work-in-progress, it still has some great material on API standards.

Performance Optimization (for Azure)
With APIs in the cloud, there are a number of issues you could run into. This github repo from Microsoft's Patterns and Practices explains some API scenarios and provides solutions with code examples. An awesome post for aspiring architects.

Best Practices for a Pragmatic RESTful API
Vinay covers a variety of topics like using SSL (like always), versioning, using verbs, JSON results (not XML...yuck!), filtering, and sorting. His post is a little long, but provides a solid checklist of how to write an API.

Securing ASP.NET Web API
Authentication and Authorization are extremely important when writing APIs. This post explains the process of building both and securing them in your API.

Best practices for REST API security: Authentication and authorization
Sam Scott and Graham Neray on StackOverflow.com provide the best practices on authentication and authorization which includes Use TLS, Use OAuth2, and Use secure API keys.

How to Design Better APIs (NEW)
These 15 language-agnostic, actionable tips on REST API design are great to review or examine when building your own APIs.

The 10 REST Commandments (NEW)
treblle.com has a great list for anyone who created a REST API. Each commandment is explained in detail with examples. This post also complements other posts on this list. It definitely serves as a great checklist.

Resources

HttpStatuses
A great reference tool for determining what your API returned and what it's trying to tell you.

API Sites

Looking to test your HttpClient? Here are some sites containing public (and not-so-public) APIs.

Tools

Postman
My favorite tool when testing APIs. It has such a wide range of settings for any API and has not failed me yet in my career.

SoapUI
Another great tool where you can test a library of APIs by simply calling and reporting on the result of the request.

Conclusion

Building standards around APIs is becoming...well, standard. While it's true that APIs are now eating the world (not software), developers should write APIs that don't cause indigestion.

How do you write APIs? Do you following a standards guide? Did I miss it in my list? Post your comments below and let's discuss.

Other Collections