API Types

There are various types of APIs available on the market today. In this article I will try to explain what should guide us in choosing the right one. What are their uses, pros and cons.

API for Operating Systems

When an application needs particular services from the operating system, such as accessing the file system or interacting with network devices and user interface elements, it utilizes the operating system API. For example, the Win32 API serves as an illustration of an operating system API frequently utilized for these tasks.

Library API

When one library exposes a functionality from another library, such as a logging API, both libraries exist within the same process. They do not communicate via any network.

Remote API

Components are dispersed across the network, indicating that they are not within the same process are probably not on the same server, virtual machine, or computer. To facilitate communication between them, they must traverse the network. Both components will be built on the same development platform.

Web API

Communication occurs over the Internet. It is applicable across diverse platforms, operating systems, or programming languages. Web APIs play a crucial role in fostering interoperability among different software systems and services on the web. They provide a standardized method for applications to communicate and exchange data, contributing to the evolution of more interconnected and integrated software ecosystems.

Web API Types:

SOAP, the acronym for Simple Object Access Protocol, serves as a communication protocol crafted for the exchange of structured information in web services. It provides a standardized approach for diverse systems to communicate over a network, often the internet. SOAP utilizes XML (eXtensible Markup Language) as its message format and can be transmitted over various protocols, including HTTP, SMTP, and others.

REST – A REST API (Representational State Transfer Application Programming Interface) comprises rules and conventions facilitating communication between distinct software systems over the internet. It aligns with the principles of REST, employing standard HTTP methods such as GET, POST, PUT, and DELETE to execute operations on resources, such as data or services. REST APIs commonly exchange data in formats like JSON or XML and are renowned for their simplicity, scalability, and statelessness, making them widely adopted for web and mobile applications.

The structure of REST API Request:

Method – HTTP Verb (GET, POST, PUT, DELETE…) URL – Location of the resource + parameters Headers – Meta-data of the request (User Agent…) Body – Contents of the request (optional) The structure of the REST API Response (Typically in JSON, it can also be XML or HTML):

Status Code – 200 (Success), 404 (Not Found), etc… Headers – Meta-data of the response (Content Type…) Body – Contents of the response (optional) RESTful APIs execute CRUD (Create, Read, Update, Delete) operations to interact with resources.

The Structure of a REST API Request:

Method – HTTP Verb (GET, POST, PUT, DELETE…) URL – Location of the resource + parameters Headers – Meta-data of the request (User Agent…) Body – Contents of the request (optional) The structure of a REST API Response (Typically in JSON, it can also be XML or HTML):

Status Code – 200 (Success), 404 (Not Found), etc… Headers – Meta-data of the response (Content Type…) Body – Contents of the response (optional) RESTful APIs execute CRUD (Create, Read, Update, Delete) operations to interact with resources.

Fundamental REST API Methods:

GET: Retrieve a resource. POST: Employed to add a resource. It should encompass a message body specifying the resource to be added and should not incorporate query string parameters. PUT: Utilized to modify resources. It should encompass a message body specifying the resource to be modified and should not include query string parameters. DELETE: Deployed to delete a resource, coupled with a parameter. It should not involve a message body.

Graph 1.0 REST API URL Structure.

GraphQL

is a contemporary query language and runtime for APIs, presenting a more effective, robust, and adaptable alternative to traditional REST APIs. Unlike fixed endpoints and responses, GraphQL empowers clients to request solely the data they require and receive it in a structured format. Initially conceived by Facebook, it has evolved into an open-source project. GraphQL operates on JSON, where queries and data are transmitted in the JSON format.

Three categories of operations are supported by GraphQL: data retrieval, data writing/modification, and subscription to changes in data. It operates on a schema, employing a predefined structure that delineates entities, fields, and attributes. Operations are formulated in accordance with this schema. Clients and servers can be built on diverse platforms, with numerous implementations accessible across various environments.

Engaging with GraphQL involves the following steps:\ Specifying the Schema. \ Crafting Queries. \ Crafting Mutations and Subscriptions (optional).\ Enacting the Logic.\

The Schema is utilized for: \ Defining the structure of data.\ Defining queries.\ Defining mutations.\ Defining subscriptions.\

The Schema employs the Schema Definition Language, a specialized linguistic framework.

gRPC

addresses the limitations of REST, including performance constraints, the reliance only on request-response interactions only, and a restricted syntax. Companies are motivated to explore alternative API implementations due to encountered problems with REST APIs.

gRPC, short of gRPC Remote Procedure Call, stands out as an open-source framework developed by Google to construct efficient and scalable distributed systems. It utilizes the HTTP/2 protocol for communication and Protocol Buffers (protobuf) as the interface description language.

In 2015, Google strategically chose to develop the next iteration of Stubby, introducing it to the open-source community as gRPC. Communication in gRPC is bidirectional over HTTP, specifically relying on the HTTP/2 protocol to overcome various performance challenges, with a key emphasis on the client-server connection.

A notable strength of gRPC lies in its support for bidirectional streaming, enabling both the client and server to exchange streams of messages. This feature proves highly advantageous for scenarios requiring real-time updates.

Although gRPC is often associated with server-to-server communication due to its sophisticated handling of HTTP/2, its reach extends to web browsers through the availability of client libraries. Despite this, gRPC is extensively utilized in native mobile apps and backend systems.

In gRPC, the client can execute specific methods on the server, offering a unique approach compared to REST, which predominantly deals with entities.

In gRPC, the client can execute a specific method on the server. In contrast, REST primarily operates with entities.

often referred to as protobuf, represents a methodology developed by Google for serializing structured data. It provides a language-agnostic format for encoding data, surpassing XML or JSON in efficiency and compactness. Protocol Buffers are extensively employed in system-to-system communication, particularly in situations where performance and data size are of paramount importance.

Protocol Buffers

gRPC stands out for its robust error-handling capabilities. Unlike REST, it does not depend on built-in HTTP errors. In the case of an error in gRPC, it returns a status code that signifies the nature of the error, accompanied by pertinent additional information.

Final verdict

The choice between REST API, GraphQL, and gRPC hinges on various factors, including your project requirements, the expertise of the development team, and the nature of the application being developed. Here are the considerations for each of them:

REST API:

Resource-Centric Operations: If your application centers around resource-centric operations and the CRUD (Create, Read, Update, Delete) functionality.\ Simplicity and Familiarity: When simplicity and familiarity are crucial, especially for small to medium-sized projects.\ Statelessness: If statelessness is a fundamental requirement for your application.

GraphQL:

Flexible Queries: If your application demands flexible and optimized data queries, allowing clients to request only the necessary data.\ Single Request for Multiple Resources: When aiming to reduce over-fetching or under-fetching of data by enabling clients to request multiple resources in a single query.\ Real-Time Data Needs: For scenarios where real-time data updates or subscription models are essential.

gRPC:

Performance and Efficiency: If performance and efficiency are paramount, especially in microservices architectures or when dealing with large-scale distributed systems.\ Strong Typing: When a strongly typed system with clear contract definitions is crucial for your application.\ Bidirectional Streaming: For scenarios where bidirectional streaming and real-time communication between the client and server are necessary.

Summary

In certain instances, a hybrid approach involving a combination of these technologies may prove appropriate, such as utilizing REST for certain aspects of the application and employing GraphQL or gRPC for specific functionalities where their strengths are evident. Ultimately, the decision rests on the particular requirements and objectives of your project.

References

• www.udemy.com
• www.grpc.io
• www.graphql.org
• www.mobilelive.medium.com