10 Rules for Designing a Successful API Program
10 Rules for Designing a Successful API Program
Let's take a look at ten rules for designing a successful API program. Also explore why these are good rules to follow.
Join the DZone community and get the full member experience.Join For Free
Back in the mid to late 90s, the web was a weird, but growing, ecosystem. Enterprises sensed the potential, and a few actually knew how to work with it. Yet the one thing everyone knew was that being online was necessary. They didn’t know exactly why, and many just used it as a directory to provide a phone number and address, but there was a perceived need. As is common with new technologies the sense of urgency caused many companies to create an online presence before they knew what the goal was.
If you want to spend 10 minutes chuckling go to http://archive.org/web/ and see how the web used to be. Design apart, you will also realize how poor the quality and utility was. As time passed expectations rose exponentially. Soon companies realized creating a website just because your competitor did wasn't a plan. It was better to take a couple months and come up with a strategy. That is the norm with most web iniatives; design and plan first, and then develop.
It is 20 years later and we are seeing this trend again with APIs. The acronym API is a bit of a misnomer, as it literally means “Application Programming Interface,” but it was created to describe something different than what it is used for now. What we most often now call APIs are internal microservices, that they expose for others to build off of. There are some enterprise companies today that are rapidly building APIs without fully understanding the use case or business need.
Simply building an API does not guarantee relevancy in today’s market. If you look at how many companies have opened an API and then shut it down, you see many have realized the simple act of creating an API doesn't make it useful. An API is a business and product decision that must be considered from every angle. Below, we have listed 10 rules for a successful API program because simply "being there" is not a victory. You will end up looking like a website from 1997 that is filled with animated GIFs and sound effects. Build for the future, not the right now.
Our 10 Rules
- Know why you’re doing it. Before you even start coding, scope why you need an API program. This is often referred to as the Business Case, or maybe even the Use Case. Know what the precise objectives are, so you know what you are building towards.
- Know what you’re doing. Have your team study and learn the best technologies and conventions. APIs are an open world, but the use of commonly used conventions can save a lot of time and expense. Shorthand: Use REST and JSON.
- Know your workflow. Since you are not the user of the APIs you are building, keep in mind that any change can destroy the work of others. Be clear on your workflow, do change announcements, and support backward compatibility as long as you can. Documentation is key!
- Know your stats (aka log everything!). Track any event, failure, or weird situation. Don’t find yourself in the position to deliver an API everybody hates, and you are the only one that doesn’t know.
- Build/buy dilemma. Some features, such as authentication, can be a complex and sensitive matter. Consideration delegating them to an API management tool such as Mashery or Oracle.
- Document your API. You cannot expect a third party to determine how you designed the API program by mere observation. Extensive documentation is required to get the community and/or third parties to successfully build with your API.
- Test the API resulting artifacts. Testing the code that generates the API is like assuming food will be good based on its ingredients. Verifying the output cleaner and simpler. It guarantees that you meet at least the minimum requirements of quality control. Moreover, you get a record of API testing reports that lead to an easier diagnosis of unexpected errors.
- Monitor API performance and availability. The second (but not secondary) aspect of API quality control is knowing when the service is doing fine. This is essential for both the API owner to help diagnose any weaknesses in the service and the API consumer that will determine when and why their product is experiencing an issue
- Ears and eyes open. Make sure testing and monitoring tools have whatever it takes to alert your staff if something happens. A great uptime record is only as good as your response when an issue does arise.
- Resources and expenses. Testing activities can be very time consuming for your already taxed dev team. In many cases, relying on external experts and consultants can be cheaper and more reliable than internal resources.
Opinions expressed by DZone contributors are their own.