Heard the term API, but don't know exactly what it means? We explain the basics and list 7 characteristics of a good API.
An API, or “application programming interface”, is a way for computer programs to communicate. These computer programs, or applications, can exist on opposite sides of the world and might not even have a common programming language, but the API gives them a connection, or interface, through which they can exchange information and commands. The API is like an intermediary or translator and enables two different programs to communicate, even if they were built using completely different technology.
APIs create a layer of abstraction that makes it much easier for developers to make use of many different applications without having to fully understand how they were built or how they really operate. The developer can just request what’s needed, when it’s needed. An API can be thought of as being like a set of rules that tells different systems how to talk to each other. These rules determine what messages can be exchanged and what information can be requested.
What are APIs used for?
You probably use lots of APIs every day and don’t even realize it.
If your phone displays weather forecasts on your home screen, that information often comes from an external service such as The Weather Company.
When you click the “Pay with PayPal” button on an online store, messages are sent via the PayPal API to make sure that the right amount is charged and that the store is notified of a successful payment.
Ever used a third-party website to book a flight or a hotel? APIs make that possible. Powerful, fast, scalable APIs such as the Skyscanner API, TripAdvisor API, and Expedia API serve incredible amounts of information to other websites every second of every day, ensuring that tickets and reservations are processed and recorded seamlessly across the internet. And even some airlines offer their own APIs, for example, Lufthansa API, and British Airways API, so that new services can be directly built using their flight information.
In fact, when you send a message to someone across the web, that message might go through an API. So even emojis can benefit from APIs ❤️
We’ll look at some more examples of real-world APIs later on, but you can probably understand by now that APIs are everywhere, and they supply a lot of the data that we rely on, even if we’re not aware of them.
7 characteristics of a good API
Developers will have their own list of requirements, but if you’re new to the world of APIs, this basic checklist should give you an idea of what’s important in a good API:
- Standardized. APIs use simple ways to communicate, such as HTTP or REST. These protocols are easy for developers to understand, widely used, and not difficult to integrate.
- Documented. An API is designed to be used by developers anywhere in the world, with the minimal need for communication with the creators of the API. So it makes sense for these developers to have access to comprehensive, up-to-date documentation. There are some great standards for creating good documentation, such as the OpenAPI specification or the API Blueprint.
- Consistent. APIs should be predictable for the developers using them. Whatever elements of the system are exposed to those developers should use consistent naming conventions and commands shouldn’t do one thing in one situation and something else in another. A good API will also handle errors in a consistent manner, so that there are no unpleasant surprises.
- Secure. Part of the point of an API is that it enables systems to interact with other systems without exposing too much information about how they operate. But that’s only part of how APIs can be kept secure. They also need to use up-to-date security certificates, be designed to resist hacking, and not leak information that isn’t intended to be shared.
- Scalable. If an API isn’t scalable, it may not be able to keep up with a lot of simultaneous requests. While that might not be a problem when it’s first launched, it could mean a complete - and costly - redesign if the architecture underlying the API isn’t optimized, or the API inherently can’t handle thousands of requests as easily as hundreds of requests.
- Simple. A good API should also be easy to use. The messages and formats used should not be so complex that they get in the way or slow things down. But that doesn’t mean it should be so simple that it doesn’t allow developers to do everything they need to do, which leads us to the last item in our list...
- Comprehensive. The ideal API gives a developer clean and clear access to data and actions. There should be no missing commands or unavailable data, if the service offers those through other means, such as on the website. Whatever you can do in a browser as a logged-in user, you should be able to do via a good API.
Unfortunately, that last point is often neglected by many websites or services, which offer stripped-down or otherwise crippled APIs that don’t let developers fully interact with their systems. This is one of the reasons that external third parties, such as Apify, step up and provide unofficial APIs that let developers do more. As the world and the web become increasingly complex and in need of automation, these enhanced APIs allow for the kind of rapid, comprehensive exchange of information that modern solutions require.
A brief history of the application programming interface
The modern API is fundamental to the internet, but the concept of application programming interfaces has existed since the early days of computers. It was always necessary to have ways to communicate with machines, even if the first commands were punched on paper cards or tape.
Database management was the first area of computing to use the term application programming interface, with the earliest mention occurring in a 1975 paper on “The relational and network approaches: Comparison of the application programming interfaces”.
But the concept of using application programming interfaces really exploded with web APIs. And that didn’t really happen until the early 2000s, when the rise of the internet meant that there was suddenly a need for lots of different programs to communicate efficiently.
So that was the start of the e-commerce APIs. Along the way, Amazon also revolutionized cloud computing with another API, for its cloud-based Amazon Web Services. That provided the scalable, fast, cheap data storage that was necessary for the next step in the rise of the API: social media.
Social media finally made APIs go viral among developers. With the Flickr API in 2004, then both the Facebook API and Twitter API in 2006, developers found that they could do some really interesting things with APIs. Widgets, embedded media, sharing buttons. All of them were built using APIs.
Social media may have made APIs cool. The shift to mobile made them essential.
The Google Maps API was launched in 2006, Foursquare in 2009, Instagram in 2011, and so on. As mobiles have become an extension of ourselves, APIs have become an extension of every popular website, in part because they aren’t going to become popular if they don’t make it easy for others to build upon their data.
The Internet of Things could well be the next phase in the evolution of the API, but let’s stop here with the history and the future and move on to some practical terms.
Useful API terms
Okay, so you know why APIs are used, you know the background, and you know what a good API should do. But what about some of those terms you hear thrown around by the devs in your company?
This is by no means an exhaustive list, but it should get you started on the basics and let you hold your own in any meetings.
What are API keys and API tokens?
You’ll probably come across some debate online as to whether an API token is different from an API key, but the two terms are often used interchangeably. So unless you’re working with a developer or company that specifies the difference between them, you can usually assume that an API key is the same as an API token.
This is the identification an application needs to communicate via the API. An API key can also act as authorization to communicate. It makes sense to track messages being sent to a program, as it can make sure the user with the API key has the correct permissions to access data. API keys are unique and usually look like a long sequence of random alphanumerical characters, like this:
API keys are usually not that difficult to obtain, because it’s in the interest of the API creators to make it easy for new developers to get a key. As long as the key is not abused or shared, it gives that developer access to all the messages that they need to exchange via the API, such as API calls. You can think of an API key as a secret code or a password that gets passed between one program and another.
API keys are usually kept secret, or encrypted, because they’re used for identification and authentication. If someone else gets hold of your API key or token, they could access data or resources using your credentials. That could be a security risk, or even end up costing you money.
What is an API endpoint?
An API endpoint is like an address in a system. APIs are all about sending messages and API endpoints guide those messages to the right place. So rather than just firing off a message into an entire system, API endpoints give the external program the right location to send that message.
Because they act as addresses, API endpoints are URLs and those URLs can include a lot of extra information, such as API keys or API tokens to authenticate the message.
You can think of endpoints as where the two systems touch. API endpoints are usually specific to what the developer wants to achieve. For instance, an API might have one endpoint for requests to download statistics, an endpoint to edit content, and another endpoint to search the system.
What is an API call?
And now we come to the actual messages that are sent using the API. These are known as API calls.
An API call is the process of sending a message to an application using that application’s API. An API call might just be to request information, but it can also be a request to add, update, or delete data. These break down into some simple instructions:
- GET: request data.
- POST: add data.
- PUT: change data.
- DELETE: delete data.
Those four commands are very powerful, as they mean that a simple API call can do everything necessary to work with the database on the other side of the API.
You might also hear the phrase “API request”. That’s just another way of saying API call. You can use either.
Here’s an example of an API call. The client application needs data about a user, in this example, that user is Apify CEO Jan Curn, so it sends a GET request to the server and the server responds with user information about Jan.
This is a really simple example, but it shows you how the request is sent to the server and a response is sent back with data. At the end of the day, that’s what APIs are all about.
Examples of APIs
Google Maps API
The Google Maps API is one of the big ones. Launched over 15 years ago, it gives developers access to the incredible 99% world coverage boasted by Google Maps and means that any website can use Maps to power their own projects. The Google Maps API includes access to maps, routes, and places, and has been used to create everything from immersive games to on-demand ride services.
Frustrated by the limits and restrictions imposed by the official Google Maps API? Try our unofficial Google Maps API. Apify’s Google Maps Scraper lets you get data from Google Maps fast and without limits.
The YouTube API lets developers add YouTube features to their sites, search for content, and interact with their own channels. It can be used to create playlists, add videos as favorites, and send messages.
The YouTube API is free, but it does have restrictions on how many calls can be made. If you need more, you can use our unofficial YouTube API. Bonus: YouTube Scraper lets you search and extract text even from subtitles or captions!
One of the earliest, the Instagram API has recently become very protective of its content. Users can only use it to interact with their own profiles.
But, as you might expect by now, we have a solution for that 😉
All of these solutions are powered by web scraping. And if that’s a new term to you, it might be a good idea to check out our Beginner’s Guide to Web Scraping.
What about the Apify API?
Apify (API-fy) was called after APIs because we create APIs for websites that don’t have them, or we improve APIs for websites that do. As you might imagine, we have our own API. Now that you’re familiar with some of the terms you’ll need, you can head over to our Apify API docs and see some of them in action.
If you need a custom API for a website and you can’t find anything suitable in Apify Store, just request a custom solution and we’ll API-fy any website for you 🦾