Demystifying Web APIs

The acronym API sounded jargon to me when I started learning web development. I thought it was used only on the web. I was wrong. APIs are everywhere: Web, mobile apps, desktop apps, IoT, etc.

For the purpose of this article, we are going to focus on web APIs.

But... what is an API?

I am glad you asked.

What is an API?

API stands for Application Programming Interface

In simple terms, APIs allow developers to use software programs written by other developers without knowing the underlying source code. That's why it's called an interface. Software developers normally expose an interface for other developers to use. It could be in any form: a function, a specific string(as we shall see in REST APIs), etc.

Think of APIs as car components. A driver uses the gas pedal easily without understanding the underlying mechanics of engine combustion. We could call these car components "Car Programming Interface". I know that sounds bizarre to you, but you should know that modern cars are actually programmable.

Examples of APIs:

• Browser storage API
• Browser geolocation API
• Weather forecast APIs
• Facebook create-post API

The list is endless. There are thousands of APIs out there but since I am a web developer, am going to focus on Web APIs.

Web APIs

We all love web 2.0. Don't we? Web 3.0 fanboys am sorry, this is not for you.

The web is an interconnected system of public web pages accessible through the Internet. Web APIs allow frontend applications to interact with web applications. Typically, backend developers expose public or private APIs on the web and clients(mobile, desktop, websites, etc) can use them from anywhere across the world.

Interesting!

Web applications live on servers. Think of Facebook: it exposes various APIs such as making post, personalized feeds, delete post, etc.

As a frontend developer, you don't necessarily need to know how Facebook deletes a post in their database to use the service. Just call the API and that's it. That's the power of APIs.

I love web APIs as they allow one to write dynamic, sophisticated applications, that anyone across the world can use over the internet. You only need a good frontend engineer and a UI designer.

By the way, I think APIs --among other factors-- largely contributed to the emergence of web 2.0. Web 2.0 is the web version of web-apps interaction.

So how do I make web APIs?

There are two most popular APIs on the web:

• REST API
• GraphQl API

Let's look into each in details

REST API

First, REST stands for REpresentational State Transfer. A REST API is an API that conforms to the design principles of the REST

REST APIs provide a flexible, lightweight way to integrate applications, and have emerged as the most common method for connecting web apps.

REST APIs communicate via HTTP requests to perform standard database functions like creating, reading, updating, and deleting records (also known as CRUD) within a resource. REST APIs are stateless in that both the client and the server do not know anything about each other. The clients needs to specify exactly what they wants in every request(or endpoints). A typical request looks like this: GET https://www.example.com/posts. This is a GET request that retrieves posts from the database and sends them to the client.

Each service in a RESTful architecture needs a specific URL/endpoint.

You can pick any server-side language and write a 'Hello World' REST API that returns the message 'Hello World' to a client. Congratulations son!

GraphQl API

Most developers are afraid of GraphQl because they think it's a tech buzzword beyond their experience. If you understand the traditional REST API, do not to be afraid of GraphQl anymore. Please.

According to GraphQl official documentation:

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

In GraphQl, instead of having various endpoints for various services, GraphQl defines one endpoint and you can query data programmatically using queries instead of endpoints. Think of it as SQL queries only that SQL works on the database and GraphQl on the server.

For me, I think of GraphQl as one endpoint that accepts various parameters in this format:

{
  tweet {
    name
    likes
    message
    comments
  }
}

This query, for example, returns only the fields specified in the tweet query. You may decide to omit likes in the above query and you'd only get what you ask for. This is handy to work with as you can see it looks more like the response JSON object you'd get from the server.

You can nest more objects in the likes fields, for example. Like this:

{
  tweet{
    name
    likes{
     name
     profile
     followers
         }
    message
    comments
  }
}

The likes field returns an array of likes with details about the name, profile and followers cont of the user who liked the tweet.

The logic that resolves this query is written on the server with any programming language that can implement the GraphQl implementation.

GraphQl is especially handy for huge, related data. Notice how you can nest complex related data and fetch only what you need. That's the power of GraphQl. In fact, it was created by Facebook to solve this problem.

Personally I like using GraphQl because:

• Self-documentation. GraphQl queries document themselves on the fly as you write the server logic hence easier to work with when connecting with the frontend.

• Easier to integrate web sockets. GraphQl provides something called subscriptions that clients can subscribe to and get real time updates upon any server event. Be it a mutation(update), query, etc.

• GraphQl Clients. GraphQl requires client libraries you use to query GraphQl servers. They are fan to work with. Some, such as Apollo-client, comes with inbuilt state management and a caching system out of the box. How cool?

Thanks for reading this article. Happy coding

Conclusion

Regardless of the API you use to connect with your web application, the programming logic is all the same. Always use the web API that fits your app requirements.