Web APIs: The real existential questions

The real existential questions

I was talking to my buddy Alexandre about Web APIs and we had a great general discussion on the subject. What he made me realize and what I want to bring up with you guys is that building APIs goes beyond the technical implementation. Sometimes you have to look at things from a higher point of view. He shared with me with the following questions that I found very interesting.

How do you project your backend API?
How do you protect your core business systems?
How do you enforce your IT and business policies?
How do you engage with developers?
How do you reduce the time-to-first API call?
How do you measure their use and impact?

Before reading what my views on the questions above are, take a few minutes to understand what those questions mean to you and how you would answer. Do they make sense to you?

An API is the main piece when it comes to the way your data is consumed. Your APIs may live on-premise, or they may be in the cloud. It all comes to agility. Regardless of the device, environment or location, an API is the answer as it allows fast consumption of data.

But who are your APIs really for? Having an API architecture strategy (API abstractions or levels), is something that is reflected by the type of consumers you are targeting, may it be Internal APIs, Partner APIs or Public APIs. Your consumers may not need the same type of projection. Opt to target the Public API abstraction from the start as this will shape the way your consumers consume your resources.

Once you have an architecture strategy in place, how do you make sure that your systems stay stable so that everyone can profit from it? How can you protect yourself, from attacks such as DDOS, but more importantly, how do you protect your user experience? You want users to be able to access your API without any frustration. You know that once you lose a developer from using your services, he/she usually does not come back. Rate limiting can be a solution that can be implemented to help limit the number of requests of a party, but it is not the ultimate solution. Have a plan, whether it be business or IT, on how you plan to address such area before it’s addressed by malicious users or by a consumer who does not care. In the end, it is your whole user experience that’s at stake.

The experience, however, goes even further than that. Every good business should have a data access policy. It is one way to enforce your Service Level Agreement(s), defining the limits of what your users can do and what you provide as a whole. Have you also thought about how you can keep your business rolling and as fluid as possible if you need to change some code to apply new policies? Do you apply different policies for different type of user groups(consumers)? Obviously, every area of business has different rules and policies and as such they should be widely known to your audience. Have a clear and concise document will weed out any existential questions and protect you in case of future problems (you obviously don’t want problems, right? :-)).

So your policies are in place, you have your architecture setup, and you believe you have a way to smooth out the user experience. Now what you need is users/developers to use your APIs. An API is the first contact someone will make with your product. If your APIs are too complex, most developers will sheer away from it quickly. As mentioned above, and I repeat it again because it is important, once a developer sheers away from a product, he/she usually doesn’t come back (I’m sure you can vouch for that as you’ve probably done it in the past, right? ;-)). How can you make it so that your developers want to use your APIs? Try to get actual feedback from the users and see what they like, don’t like, what they would like to have so you can keep your consumer base and increase it over time. A good way is to have a support channel like a forum, where users can see what is going on, ask questions about your products, open tickets on potential problems/bugs and make suggestions. A Slack channel can also be an excellent way to connect live with your users. You might even go beyond that by doing instructional videos and show your users how they can use your APIs to enhance their product(s) and grow their business. Knowing your are right there to guide them through will definitely enhance their confidence and will help you grow the confidence in your product as well.

Now that your users see that you are right there to accompany them in their journey, how can you reduce their “Time-To-First” API call? If you don’t know, the “Time-To-First API Call” is the time a developer needs to consume the API after reading your API documentation. How can you make it so that it gets reduced? My documentation point in my last article should give you a good head start. If your documentation contains already made examples, this can definitely give them a great head start. An API that is also self-descriptive with a solid naming convention is another way for them to quickly start using your APIs.

At this point, your user base is growing. You have all the right tools in place and you are ready to leave your beta stage and become fully public. There is so much hype and people are ready. You and your team start the countdown. 3,2,1 GO! Flip the switch to fully public and BOOM! You get a massive influx of calls. Are you monitoring how your API is being used? Do you think it is used properly? Are the developers hitting the right endpoints to get the data they are looking for or is there a lot of misuse? Such questions are some of the questions you should ask yourself before you fully open the valves of your APIs. Metrics are key to help you tune your APIs. They are many tools available to you that can help you with that. Application Insights is definitely one for code, but you should have a higher platform to help you with the overall look of what is happening such as an API Management in Azure.

At the end of the day…

Answering those questions can drive certain decisions, whether they are architectural or operational. Shape your APIs and what are around them like you would shape your life goals: structured, well put, well known. Remember that the real metric for your APIs is how often they are being hit/used. If they are not being used, they are pretty much nonexistent.