When you’re involved in API design, much of the hard work you’ve done to bring the API to life is invisible to the end user. Many of the APIs that ordinary consumers are happy with take mere seconds to fulfill their requests. However, getting to that point is neither as easy nor as quick for developers. There’s a lot of coding, mocking, maintenance work, and documentation to be done before the API is anywhere close to hitting the market. But one thing makes all the difference in helping developers clear all these steps in a timely and efficient manner: great API design.
As with many other software and hardware products, thoughtful design matters when it comes to APIs. It ensures smooth implementation and usage experiences, and it also sets a precedent for better work in the future. In contrast, flawed design can obstruct developers’ initial workflow, cause expensive delays, and leave something to be desired in terms of end user satisfaction. Sadly, many API developers commit the same design mistakes over and over again before they find out what they can do better. By then, they’ll have wasted time, resources, and momentum that’s hard for them to get back.
If you want to get the process right as soon as possible, avoid these six common design flaws. By doing so, you’ll make the most out of the development cycle and realize the full potential of your API.
Being Inconsistent About Design Tools and Design Environments
Consistency is one of the most important values in the API design process. But oftentimes, coding work can become very inconsistent because it isn’t executed according to a set standard. One of the best things you can do to avoid sloppy and inconsistent design work is to standardize your tools, environment, and workflow. Doing this will make it easier for you to replicate the same quality of work across different tasks.
It’s never too late to standardize your toolset and environment for the better. Try the Stoplight API design tools on Stoplight’s visual editor to achieve better consistency, as well as momentum, on your API design.
Not Following Common API Naming Conventions
You have a lot of freedom in terms of how you design your API. But in terms of approaches to take, especially for REST APIs, it’s good to stick to industry practices that are widely accepted. It ensures that you and your fellow API designers are speaking the same language when you’re deciding how to build the API. One example is the naming conventions for REST API URLs. The norm is to use plural concrete nouns, not abstract nouns or verbs. After all, URLs are supposed to direct to resources that are objects, not actions.
In short, avoid the design flaw of going against commonly accepted notions for API design. If you stick to the formula, coding work will be much less confusing on your part as well as those of fellow developers.
Being Redundant and Not Following Standard Practices When Designing Parameters
Another area of API design that sees quite a number of mistakes is the formatting of parameters. Too often, developers write code in a format that doesn’t serve a clear purpose. Other times, they may write parameters in one way for one line and then type it a completely different way in the next.
As a developer, you can avoid mistakes like these by being more careful about every line of code. The format you use should make sense, be consistent across fields, and not be a pain for your fellow developers to crack. If you trim unnecessary or redundant parameters in the body portion of each response and request, then your API design will read much more smoothly for it.
Mixing Up HTTP Methods
REST API design in particular anchors itself on the proper usage of HTTP request methods. The most well-known of these are GET, PUT, POST, PATCH, and DELETE. Whenever any of these methods are involved, they have to facilitate the kind of action that they’re commonly expected to.
To illustrate simply, GET should only be used for requests for retrieving data, while DELETE should only be used for removing the resource. HTTP request methods should never be mixed up, and should always be consistent in their usage throughout the API code. Rookie developers benefit best from reviewing the purpose of each HTTP request method. But even advanced-level developers should spend a little extra time making sure that each usage of request method aligns with its rightful purpose.
Mishandling of API Errors
No API is free from experiencing errors. In fact, the more complex the API product is, the more capable you have to be at handling errors. Thus, error messages are an important part of the API design process. Unfortunately, it’s rather common for developers to obfuscate the true nature of the error in their messages. When that happens, users are left in the dark about what went wrong in their request and why.
When writing your own error messages, it would help to detail what type of error occurred and what the user can do to fix it. To be safe, defer to HTTP protocols for different types of errors instead of going by an arbitrary error classification and error message system.
Not Keeping Track of Versions
The last on this list pertains to API versions. Though the API may have undergone a facelift at one point or another, some developers neglect to include this in their design. As a consequence, users may struggle to know which version of the API they’re using and which features are either compatible or no longer compatible.
The solution to this flaw is simple: always implement versioning on your APIs. Include version numbers on your URLs or use custom headers for each version as needed. Properly versioning your API’s resources will give your users clarity on how advanced or upgraded its features are. It will also save you and your fellow developers a lot of grief about segregating past resources and present ones.
Conclusion
In practice, an API with these design flaws may still actually work. But how well do you think it will work? How easy will it be to troubleshoot or to fix? How prepared will you and your team be to scale up the API when the time comes?
Practical, thoughtful, and consistent design will sustain an API long after its creation. Aim not only to complete the API, but to launch a product that’s representative of the best design work you can offer to your users.
