Command Palette
Search for a command to run...
Comments
Join the discussionNo comments yet. Be the first to comment.
Everything about APIs
Content List:
- Beginner's Content
- Content for the Skillful
- Advanced Content
- Conclusion
- Resources to Learn More
- List of Public APIs
- About Me
API for Beginners
Let’s start with some basics
What is API?
It's called Application Programming Interface. It is used to hide something very very complex behind something as simple as a function call. Wikipedia explains it as:
In computing, an application programming interface (API) is an interface) that defines interactions between multiple software applications or mixed hardware-software intermediaries.[1] It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow.
Duh! explain it more simply !!!
I’ll take an example, Our example for this article will be a restaurant. Let’s say today you had an awesome day (hope that you did) and you do not want to cook for yourself, so you are out for dinner in as awesome a restaurant as your day. What do you do here? You give the order to the waiter. What does he do? he brings you your food. So in this scenario, the waiter is an API, and he hides all the complexity of cooking food, decorating it on a plate, etc. This is what an API is (in a gist).
API for - Skillful
So, are there multiple types or what?
Yes, as in every programming concept, this too has multiple types.
Open APIs: These are also known as public APIs (sometimes called external APIs). These almost all of the time require an API key to be accessed. They are open for everyone to be used. They can be used by developers, corporates, and anyone else.
Partner APIs: Kind of very similar to Open APIs, but are restricted to be accessed only via a partnered gateway. If you have much experience in deployment over GCP or AWS or similar, and you use some APIs like SendGrid, Mailgun, etc via GCP/AWS/etc then you are using the partnered version of the APIs.
Composite APIs: These are APIs that allow to access multiple APIs together. Have you ever tried ordering something from a website without registering? and have you noticed that it automatically creates an account for you based on the order details? Yes, exactly, most probably that website used a composite API to place the order and create an account.
Internal APIs: These are exactly the opposite of open APIs. They are supposed to be used internally by the company itself. They allow different teams or sections of a business to consume each other’s tools, data, and programs. It helps in maintaining security, access control, and the trails of process.
These are the types of Web Service APIs (APIs that can be accessed over HTTP or the internet in simple words). They are generalized as Third Party APIs.
Another most common category of API is Browser APIs. These APIs are accessible in your browser for browser. Then there are product APIs that are meant only for the product that they are developed for and will be accessible only when you install that product. There is a whole set of Standard APIs as well, which are the proposed standards, these can be found on Openstack API specifications and W3C, and more. Another set of APIs are called System/Embedded APIs, these APIs are more specific to the system, like Windows system APIs, mobile fingerprint API, etc.
For this article, we will only focus on Web Service APIs
API for - Advanced Readers
Getting back to our example, where you have reached the restaurant and have ordered the food. (This was the part of using the front end to call the API)
Have you ever wondered what and how does the waiter writes so that the cook knows exactly what to cook and how to cook, here comes our next question
Should the APIs be called in specific ways or are they smart enough to understand our natural way of speaking?
The answer here is, obviously, APIs have some architecture and protocols. So an API protocol defines the rules for API calls.
Majorly there are 5 API architectures:
1 SOAP
2 REST
3 RPC
4 Websckets and Webhooks
5 GraphQL
I'll explain all of them in a brief.
1) SOAP (Simple Object Access Protocol)
Prior to the Rest, this was one of the most used protocols, it is heavy for transport, but provides better security than the Rest API. It is intended to be extensible and neutral. It uses XML as a format to transfer data. It also uses WSDL (Web Services Definition Language) to publish a definition of its interface. So what it means is that it uses WSDL to publish the format in which the response will be received( in very general and layman terms ).
2) REST (REpresentational State Transfer)
In today's internet, REST is one of the most followed architectures ( it is not considered as a protocol). Most of the services offered today use REST. It requires the application to adhere to some rules (called architectural constraints/principles).
-The system should be implemented over server-client architecture (which most of the time is satisfied in general). This makes the system flexible as different components of the system can be changed independently.
- The system should be Stateless: This means that the client (generally the frontend) must include all the information for the server to fulfill the request, it can be as query parameters, headers, or URI. The server should not store/maintain any states (can be thought of as sessions), all of the information should be provided by the client itself.
- Cacheability: This constraint is pretty straight, but can trouble you sometimes especially while debugging. It says that a client can cache a response, so the response must explicitly state that it can be cached or not.
- Layered system: It is also pretty straightforward, it says that the system must exist in layered format, so irrespective of whether the communication happens directly or via load balancer or different intermediaries, the API should be able to communicate.
- Uniform Interface: This is one of the most important constraints, it says that the interaction between the client and server should be uniform across all the clients ( irrespective of device or application for eg. mobile apps, web, etc). This further gets broken down into 4 sub principles: Resource-Based, Manipulation of Resources Through Representations, Self-descriptive Messages, Hypermedia as the Engine of Application State (HATEOAS). I won't be explaining these in more detail as they can be a whole blog themselves and have already have written a big para on rest, but you can visit Stackoverflow.
Richardson Maturity Model as a goalpost to achieving truly complete and useful APIs, Source: Kristopher Sandoval
3) RPC (Remote Procedure Calls)
This is a very interesting API Architecture. In the above APIs, the only thing that happens is the transfer of data, but RPC is different, it is designed to call a function instead of simply transferring data. So if you are familiar with programming, then the name itself will suggest that it calls procedures. If used for CRUD (Create, Read, Update, Delete) operations, it is like sending data fields like normally we would do, but there's a downside to this, and that is, the client is entirely in charge of everything. The client must know which methods (endpoints) to hit at what time, to construct its workflow out of the un-descriptive endpoints.
RPC is a concept that has a lot of specifications and is implemented using:
- XML-RPC: To give a brief, It simply uses XML as a data transfer format. It is also older than SOAP. XML-RPC uses minimum bandwidth and is much simpler than SOAP. XML-RPC was problematic because ensuring data types of XML payloads is tough. In XML, a lot of things are just strings.
- JSON-RPC: This protocol is similar to XML-RPC but instead of using XML format to transfer data it uses JSON. It proved out to be better than XML-RPC because to some extent it helped with the issue of data types that XML had, but it had troubles in differentiating different data formats like integers and decimals.
- Simple Object Access Protocol (SOAP): SOAP-RPC tried to resolve the issue with JSON-RPC and XML-RPC. For JSON-RPC you need to layer metadata on top to describe things such as which fields correspond to which data types. This became part of the basis for SOAP, which used XML Schema and a Web Services Description Language (WSDL) to explain what went where and what it contained.
One of the standardized formats of RPC is called gRPC it is widely accepted and used in the industry, it has been created and standardized by Google (internally the previous version was called Stubby). It is open-sourced. By default, gRPC uses Protocol Buffers (although it can be used with other data formats such as JSON). You can see who uses gRPC and why here.
4) Webhooks / Websockets API
This is for real-time APIs where data is streamed back to the calling system using technology like Websockets or Webhooks.
Sometimes Webhooks is referred to as a reverse API, but this isn’t entirely true. They don’t run backward, but instead, there doesn’t need to be a request initiated on your end, data is sent whenever there’s new data available. Webhooks are commonly used to perform smaller requests and tasks, however, there are situations where a webhook is more appropriate than an entire API.
The WebSocket API is an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.
Note: Even though for this article I have categorized them under the same umbrella, these two technologies are different.
- Webhooks are for server-to-server communication. They work by one server telling another server that it wants data sent to a certain URL when something happens.
- Websockets are (usually) for a server to browser communication. The server hosts a WebSocket server, and clients can open a connection to that server. This is popular now mostly because it is faster and less resource-hogging than older ways of solving the problem, like long-polling/COMET. It is possible to connect 2 servers using WebSockets, but that is not usually what they are used for.
This note was referenced from this Stackoverflow Reply
There are also Pub/Sub APIs that I have not covered in this post. It works on similar principles as these.
Another newer technology that I haven't written in detail is WebRTC, it is somewhat similar to web sockets but one of the major differences is that it works in real-time, especially used for audio/video communications. It is an emerging technology, with its usage increasing by the day. To get some basic understanding between WebRTC and Webscokets to refer to this article
5) GraphQL
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.
From the official GraphQL website
This is a somewhat newer API technology. GraphQL APIs have a hypermedia-like ability to use a single query to fetch the required data across multiple resources. But GraphQL APIs also borrow from concepts that we’ve observed in both REST and RPC-styled APIs.
It is a technology developed by Facebook in 2012. GraphQL was used internally for their mobile applications to reduce network usage employing its specific data-fetching capabilities. Since GraphQL specifications and reference implementation in JavaScript were open-sourced in 2015, major programming languages now support it, including Python, Java, C#, Node.js, and more. The GraphQL ecosystem is expanding with libraries and powerful tools like Apollo, GraphiQL, and GraphQL Explorer.
To understand the differences in REST and GraphQL refer to the table below:
Major differences in GraphQL and REST endpoints (Image taken from AltexSoft article)
Conclusion
So now you have a good understanding of how the waiter (in the case of the web a client) takes your order (the actions performed on UI) and organizes it accordingly so that a cook can prepare your meal (backend can process your data). These help in keeping the flow seamless even if there are tens of consecutive customers ordering (many clients interacting on the web).
Indeed, the web is a wonderful restaurant that is open and ready 24/7/365 to serve you your order. Now with this knowledge, I'll end the article, and hope to see your amazing dish (project) served (hosted) in the restaurant (web).
Below are few resources that I have referred to for this article and otherwise.
I have also collected few Public APIs for you to learn, test, and use as per your needs.
If you want to learn, how to test and use an API from basics, then I'll recommend Postman API 101 Public Workspace. Follow this to get a better grasp. They also have a webinar on this you can see it on their webinars page
Resources to Learn More
- SOAP vs REST on Postman Blog
- Why rest over RPC
- SOAP and XML-RPC
- Awesome List for resources on APIs
- Awesome List for APIs Security
- AltexSoft SOAP vs REST vs Graph vs RPC: It is also used as one of the references for this article.
- SmashingMagzine Understanding REST and RPC: A must-read to clear out the confusion and use case of RPC and REST. It is also used as one of the references for this article.
- Understanding RPC, REST, GraphQL: Another must-read for a better understanding of these APIs. It is also used as one of the references for this article.
- Web API Checklist by Mathieu Fenniak
SOAP Resources
Rest Resources
- StackOverflow Blog
- Rest 101 on Postman Blog
- Microsoft Rest API Design Blog
- Microsoft REST API guidelines
- The chapter on REST in Roy Fielding's dissertation on Network Architecture, "Architectural Styles and the Design of Network-based Software Architectures"
- How to design a RESTful API architecture from a human-language spec By Filipe Ximenesand Flávio Juvenal on O'Reilly
- Restapitutorial
- Awesome list for resources on REST APIs
- Wikipedia
Websockets / Webhooks
- Websockets on Html5rocks
- Websockets for fun and profit on Stackoverflow blog
- Benefits of Websockets on Websocket.org
- How Postman Engineering Handles a Million Concurrent Connections
- What are webhooks? on Zapier Blog
- Webhooks on Github: A amazing way to learn webhooks using Github's webhooks API.
- Webhook definitive Guide on Requestbin blog
- Webhook.site: With this site, you instantly get a unique, random URL that you can use to test and debug Webhooks and HTTP requests, as well as to create your own workflows using the Custom Actions graphical editor or WebhookScript, a simple scripting language, to transform, validate and process HTTP requests.
GraphQL
- HowToGraphql: A website built to teach GraphQL entirely for free, a must-visit website.
- Official GraphQL Docs to learn GraphQL
- Official Best Practices
- GraphQL Weekly Newsletter
- GraphQL Features, Pros, and Cons by AltexSoft
- What is GraphQL on Redis Blog
- Practical Guide of GraphQL APIs on Techbeacon
API Collections
Mixed Lists
- A whole list of APIs on Postman
- Free-for-dev List
- List of Public APIs
- APIList.fun
- Any-api.com
- Public-apis.io
- APIs guru
- Public Datasets API
- Google Maps
- Telegram
- Youtube
- Slack WebAPI
- Most famous for example purposes, NASA APIs
SOAP
- You can find some public APIs and their examples here from Postman
- Public SOAP API workspace on Postman
Rest
- Public REST API workspace on Postman
- JSONPlaceholder fake API for testing and prototyping
- REST countries
RPC
Webhooks / Websockets
GraphQL
About Me
Hey there, I am Omkar Agrawal a freelance full-stack web developer, currently, I am in the final year of my Bachelors's in Information Technology. I am also a Postman Student Leader and Postman Student Expert. I am a tech enthusiast that loves to read and learn on anything that can increase my knowledge, but especially on technology.
I am available for Backend / Fullstack development job positions, you can find me on
If you loved this blog then please support it by giving a thumbs up on this post and on other channels :