Need to understand APIs really fast? Here’s a crash course on the very basics.
What is an API?
An API (Application Programming Interface) provides a way for a developer to connect to and exchange information with an existing program or service without having back-end access to the program.
It’s a method of creating external access points for pre-programmed functions.
Throughout this guide, I’ll often refer to the program/service accessed by the API as “program” or “original program” and the developer/application using the API as “developer,” “application,” or “developer’s application.”
- Posting/Messaging: Facebook has a very popular API that allows developers to create a bot to answer questions or have conversations inside Facebook Messenger.
- Maps: Google has an API that lets developers put interactive maps and directions in websites and mobile apps.
- ATMs: ATMS use APIs to communicate with your bank, which checks your balance and updates your account when you withdraw money.
Before we get started, here are some terms you will need to understand:
- API call: What it’s called when an API communicates with the program’s server.
- Input: Information received from the user — it can be a mouse click, form field value, etc.
- Response code: A code (usually numeric) that indicates success or error performing the function on the server.
Example: 200 = success, 404 = not found
- Request: An API call makes a “request” of the server to exchange information. Requests are usually made using two methods: Post and Get.
- Post request: A request method that gives information to the server — often used to add or change information in the database (like changing a password).
- Get request: A request method that retrieves information from the server — often used to view information (like see your account details).
- Parameters: A parameter is a piece of required information that must be supplied by the user or application (like a shopper ID or product ID).
- Function: A block of code programmed to perform a specific action.
- Back-end: A slightly nebulous term that usually refers to the server-side code that performs actions behind the scenes, the part of an application a user never sees.
How APIs work
The best physical-world analogy I’ve found for an API is a restaurant menu. The menu provides a name and description for each dish you can order, and the restaurant prepares the dishes for you.
Similarly, an API provides a name and description for each operation you can access from a program, and the program performs the function for you. The main difference is that, with an API, you will have to provide some of the ingredients yourself.
It’s not a perfect metaphor, but this should give you an easier, non-technical way to think of it.
What’s happening in the diagram?
- A developer uses API documentation to find the operation that’s needed and codes the application to collect necessary input and make the API call.
Example: ATM software developer writes the ATM software to read your debit card and collect your PIN, then trigger the API call to view your balance.
- The API delivers the information to the original program’s servers.
Example: Your account information and PIN, along with the request to view your balance are sent to the bank’s servers.
- The program uses its functions and database to perform the actions designed by the API call and return the information requested. It will also provide a response code.
Example: The bank’s program authenticates your account with the PIN you provided and gets your account balance from the database. It returns the account balance to the ATM, where it’s displayed on the screen.
Information provided by an API
API documentation should provide the following information:
- API call (command, url, etc.)
- Description of what the API call does
- What kind of request can be made (Post, Get)
- What information must be included when making the call (authentication token, parameters, values, etc.)
- Possible response codes and what they mean
- Formats the call can be written in (json is common)
Why use an API?
An API acts as a middle man, or additional layer, between a developer’s application and the original program. Having the additional layer inherently offers some security to both the original program and the application accessing it. But, it’s also a good way for developers to save time.
For the original program creator …
It’s about security and service. Creating an API is a safe way to allow developers access to their service without having to let them access the program’s code or databases. It also means the program creator doesn’t have to partner with each individual developer, so it’s low maintenance as well as low risk.
For the application developer …
It’s about saving time and adding features. Why re-invent the wheel? If there’s a program out there that already performs the needed functions, the developer can write an API call into their software rather than having to do all that additional programming themselves. It also means they may be able to add features to their application that wouldn’t have been feasible otherwise.