A Checklist for Your Next API Design Review Posted in Design J Simpson April 12, 2022 When it comes time to deploy your API, it’s best not to rely on your brain’s memory to make sure you cover all the details. Even if you’ve got the best memory on Earth, you’re still likely to forget something. This is why it’s nice to have a checklist handy. An API design checklist ensures that you cover all of the important points before your API goes live. It also gives you peace of mind as you’ve got clear, concrete evidence that everything is correct before releasing your API to the public. An API design checklist is also helpful for developers learning how to create their own APIs. It lets you know what’s essential for API design and why. To help you make sure your API design is checking all the right boxes, we’ve poured over advice from API experts to put together an API design checklist. Preliminary Steps Identify Your Audience Some aspects of API design are more like developing a business than writing a program. The first item on our API design checklist is like any other business, product, or service — even if you’re not planning on monetizing it. The first thought after forming the initial idea for your API should be, ‘is there a need for this? Will people use this API?’ If the answer is yes, the follow-up question should be ‘who will use this API?’ That question can inform your API design in some surprising ways. Finding your target audience is like forming a buyer persona for marketers. It could influence everything from the text you use to the interface you choose for your UI. That’s why it’s a good idea to think about your intended audience a bit before writing your code. Create a Mockup No matter how simple your API’s going to be, it’s a good idea to create some sort of mockup, no matter how crude. Even a rudimentary drawing on a whiteboard or in your notebook can help you visualize data flow and dependencies, for instance. If you’re working with a team, collaborative design software like Miro can be highly useful. This way, everybody is looking at the same design, and everybody that’s involved can work on the same project. Delegate Tasks These first two items on our API design checklist should be considered preliminary steps, as we’re operating under the assumption you’re starting from scratch. After you’ve done some market research and mocked up your API to some extent, the next step is to create a timeline and structure for creating your API. This means delegating tasks. This is an important step even if you’re going to be doing all the work yourself. This will help you break down the entire development process into smaller, more actionable items. Even if you’re wearing many hats, you can still only wear one at a time. API Design Checklist: Before Deployment Versioning It’s always a good idea to decide on a versioning strategy for your API from the very beginning. This way, your users can anticipate changes and roll back to the original implementation if necessary. Setting up your API for versioning from the outset also means that future editions will be easy to launch. Implement Monitoring You’re going to need to know how your API is performing at every stage of its lifecycle. Putting a monitoring solution in place from the beginning will give you complete, accurate data so you can truly know how your API is performing. API monitoring experts recommend tracking metrics such as latency and execution time and keeping a record in a log. This data is helpful for all sorts of graphs, where you can monitor your API’s performance across time. Annotate Attempts Not all APIs work immediately. Stopping the development process to debug each one each time it malfunctions isn’t necessarily the best or most efficient use of your time, either. Instead, include a marker that indicates an API needs to be tested again if it doesn’t work the first time. You could easily integrate this step into an automated API testing workflow, as well. Decouple Data Before your API is ready for public consumption, you must ensure it’s secure. It’s one thing to allow an API unlimited access to data when it’s just your team using it. It’s another thing entirely for the public to be able to access any data they choose. Before you deploy your API and make it available to the public, you should separate the frontend and backend. The frontend will handle the necessary commands and implement authentication and role-based authorization policies, and then translate them and send them along to the backend. This will help ensure your API is as secure as possible. Identify Dependencies It’s critical that your API remains online and in working order once you’ve gone public. This means identifying anything that could break your API and putting failsafes in place should anything go wrong. Identifying your API’s dependencies is important to ensure your API stays up and running. Before you launch your API, you should make a note of the dependencies your API needs to function. For the sake of housekeeping, it’s a good idea to break them down into ‘critical’ and ‘non-critical dependencies’. For critical dependencies, you might create a failsafe backup protocol should anything go wrong. For non-critical dependencies, you might just log the errors for later examination. In both cases, you might want to put monitoring in place so you’re alerted if one of your dependencies fails. Trim Unnecessary Responses API requests can sometimes invoke a lot of data. This slows down response time for your API for everybody involved, for one thing. If you’re charged for data usage, that also means wasted money. Before your API goes live, it’s a good idea to put a solution in place so that only the necessary data is sent or received. This also helps reduce over-permissive states. Plan for Simultaneous Traffic When designing an API, it’s always a good idea to prepare for heavy traffic. With APIs, it’s important to remember that anything can happen. If you’re releasing a public API, you have a global audience, so it’s important to plan for traffic spikes and lulls. It’s equally important, if not more so, to plan for when that traffic happens at the same time. A first-come-first-serve approach is not necessarily the best configuration as it can leave users feeling unimportant, leading to a negative UX. Instead, you might implement a priority system, where more essential requests are handled before less pressing API calls. There’s a nearly endless assortment of ways you can divvy up the traffic to your API, though, so spend some time thinking about it before you deploy. Caching “To cache or not to cache?”, that is the question. If your API has the potential to handle a lot of data or could be slow to load for some other reason, it might be in your interest to put a cache in place. Using a distributed cache solution like AWS Elasticache or memcached are both popular and capable solutions you might try out if you decide to go that route. Decide on Access and Authentication Is your API going to be restricted or open to the public? Will it require an account? If so, what method are you going to use for API authentication? If you do decide to put something in place to track your users, you might choose to create a log of your users’ locations, whichever setup you decide to use. User Identification Speaking of user location, it’s a good idea to gather at least some data from your API regardless of what you end up using it for. The user agent used to access your API is another potential data point you might log, for instance. Login times could potentially be useful, as well. This data can be useful for everything from improving your API to refining your marketing. Spending some time thinking about what you might do with the data you harvest before you deploy will give even more clarity about how to set up your API. API Design Checklist: Final Thoughts Creating your own API is exciting, but it can also be scary. Right before launch, it can feel like herding cats while juggling a kitchen’s worth of appliances. It can be a lot, especially if you’re trying to keep track of it all in your head. While our list is not exhaustive, hopefully, our API design checklist will remove some of that anxiety so you can focus on feeling excited and proud about all of your hard work!