Mennasalam
The Web API Design Odyssey

The Web API Design Odyssey

Everything you need to know about APIs

menna abdelmeguid's photo
menna abdelmeguid
·

10 min read

Table of contents

  • Introduction

    Welcome to the gateway of innovation, Dive with me into the world of APIs, where behind the scenes of your favorite apps and websites, a secret language of digital handshakes and data exchanges unfolds. APIs, or as I like to call them, the backstage pass to the internet circus.

    In this article, I will take you on a digital journey through the vast landscape of modern technology Application Programming Interfaces (APIs).🚀🔮

APIs

APIs, or Application Programming Interfaces, play a pivotal role in modern software development. They act as bridges, allowing distinct software components to communicate and interact. They're responsible for data exchange, function calls,  

and integration between different software systems.

To facilitate these operations, there are several architectural styles.

each with its own design philosophy and use cases.

  • Folks, Do you know how to pick the right API paradigm?

    NOOOO!!!

Let's not forget the drama! Sometimes APIs can be like diva performers, they demand to be addressed just right. They're specific, demanding, and essential for a flawless performance.

But fear not Falks! I'm about to be your API Sherpa, guiding you through the terrain of handshake overload🔍🚀

Let's talk about different API paradigms:

Let's start the Battle of API Communication

  • Rest vs GraphQL

    Well, both REST or "REpresentational State Transfer "and GraphQL or "Graph Query Language" are used to build something called APIsAnd those allow different applications to communicate with each other over the Internet.

1- REST The Know-It-All of APIs:

  • REST is your most talkative colleague. It tells you everything they know, whether you want to hear it or not.

REST can be a bit of a know-it-all. You have to be specific in your requests and sift through all the data that's returned.

  • REST Terminology

  1. Resources: Resources are the fundamental concept in REST, and each resource has a unique identifier called a "URI" that identifies it as so "Uniform Resource Identifier". A client can request a response using an HTTP method.

  2. HTTP Method: these methods excel in handling simple CRUD (Create, Read, Update, Delete) operations, using Get, Put, Post, and Delete and that gets us access to those resources. And then the server responds.

  3. Respond: Respond is a representation of the resource in a format like JSON or XML.

Filter: REST also allows clients to filter, sort, and paginate the data using query parameters.

\==>But remember, if you need real-time data or operate with a highly connected data model,

REST might not be the best fit.

2-GraphQL Precise and Efficient Data Retrieval.

  • GraphQl, on the other hand, is much more reserved. They share the necessary information, but no more. But they're always willing to share more if I do ask. With GraphQL, you can be precise and only retrieve the needed data. So that GraphQL prioritizes, giving clients exactly the data they request and no more.

"Did you say clients?

Let me explain. An API is designed to receive requests from a client, which could be a web application, a mobile app, or any similar platform. The API then retrieves the required data from the server and returns it to the client for further processing."

  • GraphQL Terminologies

  1. Schema:

    in GraphQL, we have something called a "schema". This is the blueprint that defines all the possible data that clients can query through a service. Did I say "query"?

  2. Query:

    Yeah, query. That's the next one. So, a query is a request for data that follows the structure defined in the schema.

  3. Resolver:

    The resolver is called to retrieve the data requested in the query. This may involve fetching data from multiple data sources and assembling it into a response that matches the query structure.

  4. Mutations:

    And mutations, their job is to modify data on the server. So, if we think of this in terms of the "Create, Read, Update and Delete" or the CRUD model, a query that would be equivalent to the "read" in the CRUD, and then all the others, the create, the update, and delete, they're handled by the mutations.

  • Why should I choose YOU?!

  • REST APIs often require multiple requests to fetch related data,

    while GraphQL can fetch all the data in a single request

    using a complex query that follows the schema, so clients get what they request with no over-fetching.

  • REST APIs are well-suited for applications that require simple CRUD-like operations.

    So for example, an E-commerce website might use a REST API to allow customers to browse products, add items to their cart, and complete orders.

    In that case, the API would use the HTTP methods we talked about - get, put, post, and delete to manipulate the data, like the products, the orders, and the customer information.

  • Now, on the other hand, GraphQL is better suited for applications that require, well, a bit more complex data requests. What I mean by that is that we have examples of many sorts of nested fields or multiple data sources that we need to pull from.

    So if we think about a company that provides a suite of financial planning tools for its clients, those tools might require data from multiple sources.

    So they might need to go to bank transactions, investment portfolios, and credit scores.

    SOAP vs gRPC

  • gRPC VS SOAP

3-gRPC

What is gRPC? and when should we use it?

Let’s take a look.

gRPC is an open-source remote procedure call framework created by Google in 2016.

But first, what is a remote procedure call?

local procedure call is a function call within a process to execute some code.

A remote procedure call enables one machine to invoke some code on another machine.

  • gRPC is a popular implementation of RPC.

  • Many organizations have adopted gRPC as the preferred RPC mechanism to connect a large number of microservices running within and across data centers.

Let’s dive a little deeper.

First, gRPC has a thriving developer ecosystem. It makes it very easy to develop production-quality and type-safe APIs that scale well.

The core of this ecosystem is the use of Protocol Buffers as its data interchange format.

1-Protocol Buffers is a language-agnostic and platform-agnostic mechanism for encoding structured data.

2-gRPC uses Protocol Buffers to encode and send data over the wire by default.

3-By supporting many programming languages, the client and server can independently choose

4- Another reason why gRPC is so popular is that it is high-performance out of the box.

Two factors contribute to its performance:

  • First is that Protocol Buffers is a very efficient binary encoding format.

It is much faster than JSON.

  • Second, gRPC is built on top of HTTP/2 to provide a high-performance foundation at scale.

WE can talk about HTTP/1 ,HTTP/2 and HTTP/3 in another BLOG.

gRPC Flow example

In this example, the Order  Service is the gRPC client, and the Payment Service is the gRPC server.

  • Client Stub is the API Gateway

  • gRPC sends the data over the network as a stream of HTTP/2 data frames,

    because of binary encoding and network optimization, gRPC is said to be 5X faster than JSON.

Why do we not see widespread use of gRPC between web clients and web servers?

One reason is that gRPC relies on lower-level access to HTTP/2 primitives.

No browsers currently provide the level of control required over web requests to support a gRPC client.

It is possible to make gRPC calls from a browser with the help of a proxy, this technology is called gRPC-Web.

"API Gateway?!"

  • An API gateway is a single point of entry to the clients of an application.

API Gateway sits between the clients and a collection of backend services for the application.

  • An API gateway typically provides several important functions.

  1. Authentication and security policy enforcement

  2. load balancing and circuit breaking.

  3. protocol translation and service discovery.

  4. Monitoring, logging, analytics, and billing.

  5. And finally, caching.

\==>However, if you're dealing with browser clients,

gRPC might pose some challenges due to limited browser support.

4-SOAP the venerable veteran emphasizes strict protocols

  • SOAP (Simple Object Access Protocol), is a messaging protocol used for exchanging structured data between different applications.

  • purpose of soap is to provide a standardized way to exchange data between applications, regardless of the platform or programming language used.

  • Soap API uses XML as the format for sending and receiving data, and it supports a wide range of data types, including text, numbers, dates, and

    binary data.

  • soap also supports multiple transport protocols, including HTTP, SMTP, and FTP.

    1. DON'T PANIC I WILL EXPLAIN!!!!!!!!!!!!!

    2. SOAP over HTTP:
      The most common usage of SOAP is over HTTP. In this scenario, SOAP messages are encapsulated within HTTP requests and responses. The SOAP message is embedded in the body of the HTTP request or response, allowing it to be transmitted over the web. This is often referred to as "SOAP over HTTP."

      Example:

       POST /webservice HTTP/1.1
 Host: example.com
 Content-Type: text/xml
 Content-Length: 297

 <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header>
     <!-- SOAP Header -->
   </soap:Header>
   <soap:Body>
     <!-- SOAP Body -->
   </soap:Body>
 </soap:Envelope>
 ```

    3. SOAP over SMTP:
      SOAP can also be transmitted over SMTP, which is commonly used for email communication. In this case, the SOAP message is included as the body of an email, and the email is sent using SMTP.

      Example:

       From: sender@example.com
 To: recipient@example.com
 Subject: SOAP Message

 Content-Type: text/xml

 <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header>
     <!-- SOAP Header -->
   </soap:Header>
   <soap:Body>
     <!-- SOAP Body -->
   </soap:Body>
 </soap:Envelope>
 ```

    4. SOAP over FTP:
      SOAP messages can also be transmitted over FTP, which is primarily used for file transfer. In this case, the SOAP message is treated as a file and uploaded or downloaded using FTP commands.

      Example:

      Copy

       USER username
 PASS password
 PUT soap_message.xml
 ```

 The SOAP message is stored in the file `soap_message.xml` and uploaded to the FTP server using the `PUT` command.

  • one of the essential features of soap API is its ability to define a set of rules for exchanging messages  

    between applications. these rules are defined in the web services description language (WSDL), which specifies the format of the soap message and the operations that can be performed on it.

"when to use soap API"

  • soap API is an excellent choice when building applications that require a

a highly secure and reliable method of exchanging data between applications, Soap API is also suitable for building applications that require advanced security features, such as digital signatures and encryption.

  • Enterprise-level applications that require complex data structures and business logic.

\==> However, if you're working on a lightweight mobile app or a quick prototype,

1:13

SOAP might be overkill due to its complexity and verbosity.

  • Webhook VS Websocket

5-Webhook c

It's all about event-driven,  HTTP callbacks, and asynchronous operations.

Webhooks are a mechanism that allows web applications to communicate with each other in real time. They are user-defined HTTP callbacks triggered by specific events.

Use Cases:

  • Automated Updates and Notifications: Webhooks are commonly used for automated updates between different platforms. For example, when a new item is added to an e-commerce platform, a webhook can trigger an update on a related inventory management system.

  • Real-time Notifications: They enable real-time notifications, enhancing user engagement by delivering instant alerts or updates.

For instance, GitHub uses webhooks to notify your other systems whenever a new commit is pushed.

\==>But remember, if you need synchronous communication or immediate response, webhook might not be your best bet.

6-WebSocket The Real-time Communication

WebSocket is all about real-time, bidirectional, and persistent connections.

It's perfect for live chat applications and real-time gaming, where low-latency  data exchange is crucial.

WebSockets represent a bidirectional communication channel between a client and a server over a single, long-lived connection. Unlike traditional HTTP connections, which are stateless, WebSockets provide a full-duplex communication channel that allows data to be sent and received simultaneously.

Use Cases :

  • Real-time Chat Applications: WebSockets are commonly employed in chat applications, enabling instant message delivery.

  • Live Feeds and Updates: They facilitate live updates in applications such as social media feeds or collaborative editing tools.

\==>But if your application doesn't require real-time data, using WebSocket might be an unnecessary overhead.

TLDR!!

  • Introduction to API architecture

  • REST The Know-It-All of APIs

  • GraphQL Precise and Efficient Data Retrieval

  • gRPC and the Protocol Buffers

  • SOAP the venerable veteran emphasizes strict protocols

  • Webhook The Bridge to Seamless Integration

  • WebSocket The Real-time Communication

  • Do you have any idea which API Security you will use?

....NOOO?!Then you can follow me to know more about it😎

Thank you for reading my blog! I hope you found it informative and helped you to start your data journey ♥️.

Let's share knowledge and support each other's growth! ❤️

Web DevelopmentAPIsAPI GatewaydevelopmentAPI basics REST APIsoapgRPCwebhooksGraphQLwebsockets