How to use APIs
This is the second of a series of articles intended for those who are new to programming and are interested in starting to know more about APIs. You can check the previous article here.
If you’re already a developer and are searching for in-depth content Pipefy API documentations, please go here.
What are APIs used for?
Communication. This is the key word here.
It’s behind everything we do with computers (and as human beings as well).
Even programming has in its essence the need to communicate with computers. Coding is just something we invented to accomplish that and it has been working so far. Maybe in the future even coding won’t be necessary if we can communicate with computers in a better way.
That’s why we code using programming languages.
With APIs we can have the same approach. Let’s make a small recap about it:
As we discussed in our first article, Application Programming Interface is a set of functions that applications provide to establish connections with them, allowing interactions and exchanging information. In other words, that’s how applications communicate with each other.
Without API’s we couldn’t use computers how we do today. The reason for this is that they’re not exclusive to the web. The Operational System of our computers and every programming language has APIs.
Remember that API is an interface that offers an abstraction of complexity and it can be applied to any context in the computer science area.
Have you ever heard about binary code? The 0s and 1s that computers understand? So when we’re programming, it’s not necessary to communicate ourselves with computers using binary code directly anymore, and it would be exhausting. Many abstractions and interfaces were built on top of it to let us write programs almost in our common spoken and written languages.
But let’s get back to a more familiar context: the web.
The tech community has been observing the Web APIs usage rising for many years now.
The internet, created to connect people through computers, is in constant evolution and one of the aspects of this progress is the improvement of communication between different services.
Today, many platforms like social media, marketplaces, e-commerce and applications in general, have developed their own APIs. Any digital company has one or many of them available and they’re creating new values and opportunities for these companies. APIs are becoming the heart of the modern web, enabling different services to share information and resources and having some kind of cooperation.
What can be done using API?
In addition to all the services that you use on the web being built on top of APIs, we commonly see another word related to this subject: integration. It’s pretty common to see these two words together, as API integration.
Many low code and no code applications are taking advantage of these features to bring powerful resources to their users and there are even some companies offering this type of service, called iPaaS (Integration Platform as a Service).
So that’s one of its powers – to build integrations.
Like in our previous article example, where we had an example of an API request getting books information from an e-commerce to store it in a personal library spreadsheet, you can apply the same thinking to any service you’re using: audio, video and media streaming, email services, banking services, delivery platforms and any other platform that you can imagine. It’s really awesome! Think of it just like the whole world is connected!
In our working context, with integrations we can create automated workflows across platforms, which can save us a lot of work, costs, time and increase our productivity.
How do APIs work?
In order for applications to communicate with each other, a common language needs to be used. Just like us, humans, we need to set up a common way of communicating with each other and establishing protocols.
It works just like that for the web – we need protocols there – and that’s also true regarding APIs.
Everything on the internet works on top of what we call HTTP (Hypertext Transfer Protocol).
The common definition taken from MDN Docs for this acronym is:
“HTTP is a protocol for fetching resources(…). It is the foundation of any data exchange on the Web and it is a client-server protocol, which means requests are initiated by the recipient, usually the Web browser. A complete document is reconstructed from the different sub-documents fetched, for instance, text, layout description, images, videos, scripts, and more.”
Why are we talking about this? Because we need to have a basic understanding of HTTP to talk about the different types of APIs we have today, which are:
– REST APIs;
– GraphQL APIs;
– SOAP APIs.
There are more, but these ones are the most used nowadays in the web context.
HTTP has something called verbs (yet another link to regular human languages), and just like we would say we need something – “Please, get that thing for me” – there is also an HTTP verb named GET.
Another important detail for us to work with HTTP requests is the address of the resource that we need, which in this context is called endpoint. It exists because we need to set the place (or address) where we’re going to call the GET verb.
So, using the previous article example, when our spreadsheet application needed to get the books information, the API probably would make the following request:
GET https://bookstore.com/marcos_account/get_books
Which would return something like:
{
"books":[
{
"title":"Northanger Abbey",
"author":"Austen, Jane",
"year_written":1814,
"edition":"Penguin",
"price":18.2
},
{
"title":"War and Peace",
"author":"Tolstoy, Leo",
"year_written":1865,
"edition":"Penguin",
"price":12.7
},
{
"title":"Mrs. Dalloway",
"author":"Woolf, Virginia",
"year_written":1925,
"edition":"Harcourt Brace",
"price":25
},
{
"title":"The Hours",
"author":"Cunningham, Michael",
"year_written":1999,
"edition":"Harcourt Brace",
"price":12.35
},
{
"title":"Huckleberry Finn",
"author":"Twain, Mark",
"year_written":1865,
"edition":"Penguin",
"price":5.76
},
{
"title":"Bleak House",
"author":"Dickens, Charles",
"year_written":1870,
"edition":"Random House",
"price":5.75
},
{
"title":"Tom Sawyer",
"author":"Twain, Mark",
"year_written":1862,
"edition":"Random House",
"price":7.75
},
{
"title":"A Room of One's Own",
"author":"Woolf, Virginia",
"year_written":1922,
"edition":"Penguin",
"price":29
},
{
"title":"Harry Potter",
"author":"Rowling, J.K.",
"year_written":2000,
"edition":"Harcourt Brace",
"price":19.95
},
{
"title":"One Hundred Years of Solitude",
"author":"Marquez",
"year_written":1967,
"edition":"Harper Perennial",
"price":14.00
},
{
"title":"Hamlet, Prince of Denmark",
"author":"Shakespeare",
"year_written":1603,
"edition":"Signet Classics",
"price":7.95
},
{
"title":"Lord of the Rings",
"author":"Tolkien, J.R.",
"year_written":1937,
"edition":"Penguin",
"price":27.45
}
]
}
That’s it! We’ve made our first API request.
What returns from this request is called payload and that is the resource that our spreadsheet application will understand and store its content.
But we’ll get into more details about it in the following articles.
Wrapping up
So we talked about communication and how it’s a key concept to let us understand what APIs are used and why, and how it works.
They’re built on top of a common protocol called HTTP, where different applications call “communicate in the same language”.
We also discussed the API economy and how they’re becoming a powerful tool and bringing news opportunities to digital companies.
Don’t worry about the technical words present in this article, we’re going to talk more about those in the next article.
I hope the shared content could be helpful to you!
This article was written by Marcos Carvalho, Backend Developer at Pipefy