What is an API?
API stands for application programming interface. The most important part of this name is “interface,” because an API is essentially a set of requirements that govern how one application can talk to another. You still need to know the language to communicate with the program, but without an API, you won’t get far.
APIs are what make it possible to move information between programs—for instance, by cutting and pasting a snippet of a LibreOffice document into an Excel spreadsheet.
APIs do all this by “exposing” some of a program’s internal functions to the outside world in a limited fashion. That makes it possible for applications to share data and take actions on one another’s behalf without requiring developers to share all of their software’s code.
When programmers decide to make some of their data available to the public, they “expose endpoints,” meaning they publish a portion of the language they’ve used to build their program.
Other programmers can then pull data from the application by building URLs or using HTTP clients or other protocols (special programs that build the URLs for you) to request data from those endpoints.
Endpoints return text that’s meant for computers to read, so it won’t make complete sense if you don’t understand the computer code used to write it.
Basically, an API allows one program to request data from another.
How does an API work?
API's consist of three parts:
- User: the person who makes a request
- Client: the computer that sends the request to the server
- Server: the computer that responds to the request
1. Someone will build the server first, since it acquires and holds data.
2. Once that server is running, programmers publish documentation, including the endpoints where specific data can be found.This documentation tells outside programmers the structure of the data on the server.
3. An outside user can then query (or search) the data on the server, or build a program that runs searches on the database and transforms that information into a different, usable format.
Actions you can take through an API
The server has the data and sets the language, while the client uses that language to ask for information from the server.
The language and syntax of APIs severely limits their abilities. There are four types of actions an API can take:
- GET: requests data from a server — can be status or specifics (like last_name)
- POST: sends changes from the client to the server; think of this as adding information to the server, like making a new entry
- PUT: revises or adds to existing information
- DELETE: deletes existing information
When you combine the endpoints with these actions, you can search or update any available information over an API. You’ll need to check the API documentation to find out how to code these actions, as they’re all different.
While we’re talking about language and syntax, let’s cover the ways you can make a request on a server:
1. HTTP: hypertext transfer protocol. This is how you got to our site in the first place — by typing a URL in the search bar in your browser. This is a really easy way to access data, but it won’t come back to you in a pretty format if you request a lot of information.
2. Text formats: XML, JSON. These are the main languages for accessing data over an API. When you receive your data, you will need to wade through the XML or JSON code to understand what the server gave you.
In order to implement this you would require some technical knowledge or assistance.
Why should you use an API?
Computers make a lot of things easier, especially tasks that involve collecting and sorting through lots of data.
Let’s say you wanted to know how many engagements you had in your Civil Space instance. You could go to your Civil Space instance and manually count the engagements across your Projects.
On the other hand, if you were to use the endpoint `GET /api/v1/engagements` and send an authorized request, you would receive a list of all the engagements which could take much less time and be much more accurate than manually counting across all your projects across multiple brands.
APIs clearly define exactly how a program will interact with the rest of the software world— thus save time, resources and help avoid legal licence challenges.
An API is useful for pulling specific information from another program. If you know how to read the documentation and write the requests, you can get lots of great data back, but it may be overwhelming to parse all of this. That’s where developers come in. They can build programs that display data directly in an app or browser window in an easily consumable format.