Everyone is talking about APIs, and frankly, you can't build a software project today without interfacing with a dozen of them. At Tragic, we build solutions for cutting-edge startups and large enterprises – which means we have seen a lot of APIs.
We truly believe that they run the world. In this post, we define application programming interfaces (APIs) and describe how they tie into efficiently building software in 2021.
What is an API?
An application programming interface (API) is a way for one computer service to talk to another. Companies create private APIs, like the ones that send information between their cloud services and their web, mobile, and desktop apps.
Public APIs have been gaining crazy momentum these days too. Increasingly, there are entire companies that exist to build, maintain, and sell APIs to other development teams. Stripe (payments), Twilio (SMS and email), and Algolia (search) have swelled to multi-billion dollar valuations by perfecting APIs.
Increasingly, there are entire companies that exist to build, maintain, and sell APIs to other development teams.
There is even an entire ecosystem of tools to support developers. Postman, Kong, Apigee (sold to Google Cloud), RapidAPI and others help with the scaffolding – like testing, securing, monitoring, and documenting your API.
Whether you like them or not, APIs are here to stay and your company will likely rely on them more and more as time goes on.
Building Software in 2021
Building software in 2021 is interesting. On one hand, developer tools, frameworks, and cloud infrastructure are incredibly advanced. Things that used to take you weeks to build and deploy can be done in a handful of clicks.
On the other hand, rarely do you build an application – or even a backend service – entirely from the ground up. It's all integrations, all the time.
If you build software, you will (i) use open source APIs, (ii) purchase APIs from vendors, and (iii) maintain your own internal APIs. You have to make important decisions from the beginning to understand what you will build and what you will integrate.
And yes, if you get this wrong, it will become a mess. Thanks for asking.
1. Don't Suck
This is great advice across the board. If you are going to publish an API, we would appreciate using modern conventions, clearly describing what you do, and having a FAQ so we can get a sense if this service will work for our product.
Technology is changing all of the time, so it's important to keep things up-to-date or (at a minimum) communicate the level of updates that can be expected. There are huge numbers of archaic APIs sitting around becoming increasingly obsolete and extremely painful to integrate.
Whether it's from locking documentation or outdated programming interfaces, if your API is painful to work with, developers will find a replacement. We've seen firsthand that clients migrate to another API due to developer frustration.
We have so many examples of APIs that suck. We could name names, but we won't. But we could!
2. Please Stop Using SOAP and XML
Attention all teams: please stop using SOAP and XML. Simple Objects Access Protocol (SOAP) and Extensible Markup Language (XML) are old ways of passing data around and there are much, much better ways of doing it today.
At Tragic, we use both RESTful and GraphQL APIs. Being able to quickly query for the data you want and receiving that data as JavaScript Object Notation (JSON) has been incredibly transformative in the ease it takes to consume and manipulate data.
We are particularly fans of GraphQL as it allows us to query the exact data we need, instead of having to stitch together multiple API calls.
3. Strong Documentation
Documentation can transform an API.
In particular, docs need to explain how the application programming interface works and how to use the API. For instance, good docs will provide you with a clear outline of request bodies and response bodies, along with examples showing how to pass data.
Bad documentation is poorly organized, incorrect, or just missing entirely. For instance, we have seen outdated documentation cause problems because you are following the docs but the API itself has been updated and slightly modified.
When using an API, small things like using the wrong date format or leaving out a semicolon can cause errors. If the documentation or error messages are not descriptive, it can take hours to debug a simple issue.
The gold standard for documentation, in our opinion, is Stripe.
4. Getting Started Guides for Popular Languages
Continuing on from documentation, it makes a huge difference to have a getting started guide or quickstart repository for popular languages, like JavaScript, Python, and PHP. Every developer is trying to build something different, but there are common use cases.
For payments, it's accepting credit cards online. For email, it's how to add user data to your mailing list and send out programmatic emails. Regardless of what you are building, you need to outline your top handful of use cases step-by-step.
A junior developer should be able to select their language of choice and follow your steps to get to an end result. If you can make the steps that clear, without leaving a developer frustrated, then you have a winner on your hands.
Conclusion
Application programming interfaces allow different services to talk to one another. This could be your backend talking to your mobile app or it could be a third-party service that allows you to accept payments, send emails, or check the weather in a region.
Regardless, your software project will rely on a dozen APIs to run. That means you need to carefully build, test, and monitor your API integrations. And if you are publishing an API that other teams can use, then you need to go a step further.
If integrating with your product is painful, it will deter organizations from using it. It's 2021 and developer experience (DX) really matters.
Have questions about APIs and integrations? Contract Tragic today for a free evaluation. Our experienced development team is here to help.
