Build Your API Like It’s an App; The Importance of Testing & Monitoring
APIs are one of the most attractive of today’s developer trend. SmartBear’s Lorinda Brandon says an overlooked secret to API success is to think about (and build) your API like it’s an application. She shares a savvy step-by-step guide.
by Lorinda Brandon, SmartBear Software
API Partner Development
"Although APIs don’t have user interfaces (like applications do), you still want to deliver a good user experience."
There has been a lot of discussion over the last few years about treating your API like it's a product. Indeed, your API has consumers, and often the business has bottom-line expectations. So, it makes sense that your APIs go through some of the same rigorous processes as your products do.
But "product" is a vague business-y term that implies requirements, business models, market analysis… stuff like that.
For IT professionals, I think it makes more sense to talk about treating your API the way IT would work on an application. It implies more structure and process to the API project.
You wouldn't release an application without doing some testing, even if it's just unit testing. You would also set up some production monitors, just to make sure the application is still functional. Another step, you wouldn't forget to document an app or invest time in designing a friendly user interface. All these same steps also hold true for successful APIs.
So, in this article, I'll take a closer look at what it means to build and manage your API like it's an application. One way I think about this is to ask (and answer) the right questions at the right time. So, let's get started:
When you design an application, you don't normally start with the architecture. First and foremost, you identify what the purpose of the application is, who its users are, what their experience will be with it.
Rather than architecture, start with a clear sense of purpose and audience. This leads to a better user experience. So what are the questions you need to ask and answer when designing your API?
Why? Why are we building an API? What purpose is it supposed to serve? An API that is intended to streamline your internal development has different requirements than an API that is intended to build your brand and boost your bottom line.
Who? Who will consume this API? If you are building an API for internal developers or partners to consume, the testing and documentation needs are vastly different than if you are building a public API. Another thing to consider is the skill level of the API consumers you are targeting. Do they need something more than metadata and a dev portal – like a cookbook, for example?
Develop and Test
Once you understand the goal of the API and the persona you are targeting, it's time to lay out the architecture that lets you build the right application. Just as you would when building applications, you need to need to answer more tactical questions during the development phase.
What? You know the purpose of the API and who it's intended for. So now you need to identify what the API consists of. This is analogous to laying out the wireframes for an application.
For an API, think of it this way: What are you going to build in order to meet the requirements of the business? This can take the form of an API description like Swagger, API Blueprint, IO Docs, or even WADL/WSDL. In real technical terms, your service description now also becomes your wireframe that helps you meet business goals.
How? Apps and APIs have a lot in common when it comes to answering the ‘how' part. Even when you know what you're building, you still need to define how you're going to build and test it.
Although APIs don't have user interfaces (like applications do), you still want to deliver a good user experience. Creating a detailed service description, along with a virtual version of your API, will let your testers exercise the API, as well as develop test plans and skeleton frameworks. You'll even find you can build your API in the same Agile fashion as you build your applications.
Deploy and Monitor
Not all applications are built the same way -- so they won't all be deployed on the same platform or monitored on the same frequency. This is also true of APIs. To launch and operate APIs, here are the most important questions.
Where? Before you decide where to host your application, you'll consider a lot of factors like performance requirements, load balancing, and stability. Use the same considerations for APIs.
For example, if you expect your API to have peak load times, you might want to consider a cloud solution with elasticity so you can meet the load and performance requirements without any impact to your business. If your API provides business-critical functionality or provides critical data to its consumers, you should choose a platform that will provide stability, reliability (and even scalability).
When? How frequently an application is monitored often depends on how critical an application is to your business or your mission. This is when you need to determine the amount of risk you can absorb with your API. Higher the risk, the more frequent the monitoring.
If your API is mission- or business-critical for you or your external consumers, you should make sure to monitor more frequently so you can catch any issues before they become escalated.
Finding a balance between the technical conversation and the business conversation can be challenging when it comes to APIs. When we all started the chant about treating your API like a product, we were trying to overcome the business aversion to defining requirements and roadmaps for APIs despite how tied they have become to business strategy.
But as the API industry grows up, it's time to move beyond the high-level considerations like roadmaps and into the tactical realities. If we use what we've learned about building high-quality applications iteratively and apply that same science to building high-quality APIs, we all succeed.
Lorinda Brandon is Director, API Partner Development at SmartBear Software, a provider of software quality tools for the connected world. She is a superstar speaker on all things API and a strong advocate for women in IT, promoting the importance of closing the gender gap for upcoming generations. Follow Lorinda on Twitter @lindybrandon.
- SmartBear Looks To Speed Up Design, Documenting APIs with Updated, Unified Swagger UI and Editor
- ‘Full Life Cycle’ API Management Can Drive Competitive Advantage
- Tibco’s ‘Hybrid Gateway’ for APIs Delivers New-Gen Platform for Digital Business
- DreamFactory: Next Chapter in ‘Cool APIs’ May Come with API Automation for App Building
- Cool APIs: Top Tips To Secure Valuable APIs Against Growing Security Threats