Back in the mid to late 90s the web was a weird growing ecosystem. Enterprises sensed the potential, and a few actually knew how to work with it, but 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.
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 currently call APIs are web services that are exposed to others to build software off the data and logic of the API owner. There are some enterprise companies today that are rapidly building APIs without fully understanding the use case or business needs.
Simply building an API does not guarantee relevancy in today’s market. An API is a business and product decision that must be considered from every angle. Below we have listed 10 rules to 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 past.
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 a open world, but the use of commonly used conventions can save a lot of time and expense.
- Know your worflow. 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
- 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 Apigee.
- 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 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.