When you set out to build your first API, it can very well be that you are either overwhelmed or forget essential points. The ecosystem for API tools is vast, and it's vital to get the right tool for every phase of your project.
In this article, we will go through the different phases an API project usually has. For every phase, I will list the significant points and tools that help there.
Build Phase
The first phase is the build phase. It's defined by major decisions we have to make before we start implementing and later the actual implementation of our API. We have to ask what type of API we want to build. Is it RPC or REST? Do we have to push updates to the users in real-time, or can we get away with a pull-based approach?
Depending on the requirements our use-cases have, we have to choose technology that fits. On the other hand, we also have to keep an eye on our developer's skillset; if we select tech nobody can handle, we won't build anything good.
Design
Design tools can help us with planning our API and even generating common parts of it. They force us to follow best practices, so even less-skilled personnel can build secure and performant APIs.
Usual API design tools include:
Also, a side note, before using the tools it is important to understand API design patterns. Learn more.
Mockup
Mockup libraries are another part of the toolbelt. They can be used for testing and help client implementers to start building before the actual API is ready.
Common API mockup libraries are:
Language/Runtime
While some programming languages, like Go, were created to build APIs, and languages like Elixir are exceptionally well-suited for parallel programming, they are often chosen by the workforce's available skills.
It's also important to note that the language often prescribes the framework. But some approaches to API frameworks, like the Sinatra-like, have an equivalent in most languages.
Some languages that are commonly used to build APIs are:
Moesif also have a list of API resources by language here at API Guide
Framework
Like with programming languages, frameworks are complex constructs, so choosing one will often depend again on the skills of your workforce. Some are more minimal; some are more full-featured. Some languages provide more out of the box and don't need much framework tooling at all.
These are some frameworks that power APIs all over the internet:
Test & Deploy Phase
The test and deploy phase is about getting the whole project production-ready, consistent, and hosted in a data center of your choice. Again, some tools restrict other decisions. For example, Amazon API Gateway is only available from the cloud provider AWS.
Cloud Providers
The offerings of cloud providers differ a bit, and they have different strengths. Heroku is straightforward to use. AWS has the newest tech earliest, Azure integrates very well with the Microsoft ecosystem, and Google Cloud is at the forefront of machine learning technology.
The biggest cloud providers are:
Gateway
API gateways help to manage different parts of your system and provide a central entry point. Some are open-source, some not. Some are managed, some self-hosted. There is a wide variety of gateways to choose from.
The most used gateways are:
Testing
Automated testing of your API helps to keep the development velocity from slowing down. Getting things right at the beginning is one thing, but keeping things right over the lifetime of an API project is another story.
Testing services and frameworks that can help with this task are:
Monitoring
When you're deploying an API to the internet, in a data center far away, it's crucial to have a way to know what it is doing. You can't let errors go unnoticed, and you don't want to over- or under-provision your system. There are two different types of
monitoring. Synthetic Monitoring like Runscope which pings your API on a set schedule and Real User Monitoring like
Moesif which monitor API traffic from customers.
Excellent hosted monitoring services are:
Publish & Share Phase
When you got your API ready for prime time, you want to share it with the world, but you also want the world to use it and see how it does so. Documentation and analytics are essential for this.
Documentation
Proper documentation makes or breaks an API business. After all, if nobody understands how to use your system, it doesn't help that it's super innovative.
Luckily for you, there are many documentation tools out there that help:
Analytics
Analytics, like monitoring, is a method to track metrics on the the health of your APIs, but analytics goes one step further aligning
monitoring to business value and customer demographics. This provides visibility into customer API usage for teams beyond infrastructure such as product, sales, and marketing teams to understand how customers adopted and used your APIs.
Some tools like Moesif can also track user behavior and web activity which enables sophisticated product analytics like tracking a funnel from initial sign up to first API Call.
API analytics can answer business questions like: Do customers that came in via one channel behave differently than customers that came in via other channels? Or more concrete, do customers I got via Twitter churn more than customers I got via Google ads?
Looking for a complete customer-centric API analytics solution? Check out Moesif!
This article was originally written for the Moesif blog.
Top comments (6)
Hi! Thank you for sharing this article. Regarding the API Mocking. I could not get passed through JSONStub registration, the project seems to be very outdated and not sure if it is still supported at all. I was trying in the past Beeceptor, but it is very limited and also seems to be pretty outdated. Would be interesting to hear if you've tried QuickMocker before and what do you think about it?
I didn't try it,
but good to see that new things are popping up :)
any takes on resthooks.org?
reduce api server load by 66x! imagine how much hypermedia controls and self description and ALPS you could put in the payload then! also hoppscotch.io is nice too
Never heard of it, but sounds interesting, thanks!
Thank you for the great resource! I’m starting to build an API for myself and this was super helpful to see where my gaps are!
Glad I could help :)