Architecture styles define how different components of an application programming interface (API) interact with one another. As a result, they ensure efficiency, reliability, and ease of integration with other systems by providing a standard approach to designing and building APIs. Here are the most used styles.

REST API vs. GraphQL

When it comes to API design, REST and GraphQL each have their own strengths and weaknesses.

The diagram below shows a quick comparison between REST and GraphQL.

REST

• Uses standard HTTP methods like GET, POST, PUT, DELETE for CRUD operations.
• Works well when you need simple, uniform interfaces between separate services/applications.
• Caching strategies are straightforward to implement.
• The downside is it may require multiple roundtrips to assemble related data from separate endpoints.

GraphQL

• Provides a single endpoint for clients to query for precisely the data they need.
• Clients specify the exact fields required in nested queries, and the server returns optimized payloads containing just those fields.
• Supports Mutations for modifying data and Subscriptions for real-time notifications.
• Great for aggregating data from multiple sources and works well with rapidly evolving frontend requirements.
• However, it shifts complexity to the client side and can allow abusive queries if not properly safeguarded
• Caching strategies can be more complicated than REST.

The best choice between REST and GraphQL depends on the specific requirements of the application and development team. GraphQL is a good fit for complex or frequently changing frontend needs, while REST suits applications where simple and consistent contracts are preferred.

Neither API approach is a silver bullet. Carefully evaluating requirements and tradeoffs is important to pick the right style. Both REST and GraphQL are valid options for exposing data and powering modern applications.

How does gRPC work?

RPC (Remote Procedure Call) is called “remote” because it enables communications between remote services when services are deployed to different servers under microservice architecture. From the user’s point of view, it acts like a local function call.

The diagram below illustrates the overall data flow for gRPC.

• Step 1: A REST call is made from the client. The request body is usually in JSON format.
• Steps 2 - 4: The order service (gRPC client) receives the REST call, transforms it, and makes an RPC call to the payment service. gRPC encodes the client stub into a binary format and sends it to the low-level transport layer.
• Step 5: gRPC sends the packets over the network via HTTP2. Because of binary encoding and network optimizations, gRPC is said to be 5X faster than JSON.
• Steps 6 - 8: The payment service (gRPC server) receives the packets from the network, decodes them, and invokes the server application.
• Steps 9 - 11: The result is returned from the server application, and gets encoded and sent to the transport layer.
• Steps 12 - 14: The order service receives the packets, decodes them, and sends the result to the client application.

What is a webhook?

The diagram below shows a comparison between polling and Webhook.

Assume we run an eCommerce website. The clients send orders to the order service via the API gateway, which goes to the payment service for payment transactions. The payment service then talks to an external payment service provider (PSP) to complete the transactions.

There are two ways to handle communications with the external PSP.

• Short polling

After sending the payment request to the PSP, the payment service keeps asking the PSP about the payment status. After several rounds, the PSP finally returns with the status.

Short polling has two drawbacks:

• Constant polling of the status requires resources from the payment service.

• The External service communicates directly with the payment service, creating security vulnerabilities.

• Webhook

We can register a webhook with the external service. It means: call me back at a certain URL when you have updates on the request. When the PSP has completed the processing, it will invoke the HTTP request to update the payment status.

In this way, the programming paradigm is changed, and the payment service doesn’t need to waste resources to poll the payment status anymore.

What if the PSP never calls back? We can set up a housekeeping job to check payment status every hour.

Webhooks are often referred to as reverse APIs or push APIs because the server sends HTTP requests to the client. We need to pay attention to 3 things when using a webhook:

• We need to design a proper API for the external service to call.
• We need to set up proper rules in the API gateway for security reasons.
• We need to register the correct URL at the external service.

How to improve API performance?

Pagination

This is a common optimization when the size of the result is large. The results are streaming back to the client to improve the service responsiveness.

Asynchronous Logging

Synchronous logging deals with the disk for every call and can slow down the system. Asynchronous logging sends logs to a lock-free buffer first and immediately returns. The logs will be flushed to the disk periodically. This significantly reduces the I/O overhead.

Caching

We can store frequently accessed data into a cache. The client can query the cache first instead of visiting the database directly. If there is a cache miss, the client can query from the database. Caches like Redis store data in memory, so the data access is much faster than the database.

Payload Compression

The requests and responses can be compressed using gzip etc so that the transmitted data size is much smaller. This speeds up the upload and download.

Connection Pool

When accessing resources, we often need to load data from the database. Opening the closing db connections adds significant overhead. So we should connect to the db via a pool of open connections. The connection pool is responsible for managing the connection lifecycle.

HTTP Protocol

What problem does each generation of HTTP solve? The diagram below illustrates the key features.

HTTP 1.0

HTTP 1.0 was finalized and fully documented in 1996. Every request to the same server requires a separate TCP connection.

HTTP 1.1

HTTP 1.1 was published in 1997. A TCP connection can be left open for reuse (persistent connection), but it doesn’t solve the HOL (head-of-line) blocking issue. HOL blocking - when the number of allowed parallel requests in the browser is used up, subsequent requests need to wait for the former ones to complete.

HTTP 2.0

HTTP 2.0 was published in 2015. It addresses HOL issue through request multiplexing, which eliminates HOL blocking at the application layer, but HOL still exists at the transport (TCP) layer.

As you can see in the diagram, HTTP 2.0 introduced the concept of HTTP “streams”: an abstraction that allows multiplexing different HTTP exchanges onto the same TCP connection. Each stream doesn’t need to be sent in order.

HTTP 3.0

HTTP 3.0 first draft was published in 2020. It is the proposed successor to HTTP 2.0. It uses QUIC instead of TCP for the underlying transport protocol, thus removing HOL blocking in the transport layer.

QUIC is based on UDP. It introduces streams as first-class citizens at the transport layer. QUIC streams share the same QUIC connection, so no additional handshakes and slow starts are required to create new ones, but QUIC streams are delivered independently such that in most cases packet loss affecting one stream doesn't affect others.

SOAP vs REST vs GraphQL vs RPC

The diagram below illustrates the API timeline and API styles comparison. Over time, different API architectural styles are released. Each of them has its own patterns of standardizing data exchange. You can check out the use cases of each style in the diagram.

Code First vs. API First

The diagram below shows the differences between code-first development and API-first development. Why do we want to consider API first design?

• Microservices increase system complexity and we have separate services to serve different functions of the system. While this kind of architecture facilitates decoupling and segregation of duty, we need to handle the various communications among services. It is better to think through the system's complexity before writing the code and carefully defining the boundaries of the services.
• Separate functional teams need to speak the same language and the dedicated functional teams are only responsible for their own components and services. It is recommended that the organization speak the same language via API design. We can mock requests and responses to validate the API design before writing code.
• Improve software quality and developer productivity Since we have ironed out most of the uncertainties when the project starts, the overall development process is smoother, and the software quality is greatly improved.

Developers are happy about the process as well because they can focus on functional development instead of negotiating sudden changes. The possibility of having surprises toward the end of the project lifecycle is reduced. Because we have designed the API first, the tests can be designed while the code is being developed. In a way, we also have TDD (Test Driven Design) when using API first development.

HTTP status codes

What does API gateway do?

The diagram below shows the details.

• Step 1: The client sends an HTTP request to the API gateway.
• Step 2: The API gateway parses and validates the attributes in the HTTP request.
• Step 3: The API gateway performs allow-list/deny-list checks.
• Step 4: The API gateway talks to an identity provider for authentication and authorization.
• Step 5: The rate limiting rules are applied to the request. If it is over the limit, the request is rejected.
• Steps 6 and 7: - Now that the request has passed basic checks, the API gateway finds the relevant service to route to by path matching.
• Step 8: The API gateway transforms the request into the appropriate protocol and sends it to backend microservices.
• Steps 9-12: The API gateway can handle errors properly, and deals with faults if the error takes a longer time to recover (circuit break). It can also leverage ELK (Elastic-Logstash-Kibana) stack for logging and monitoring. We sometimes cache data in the API gateway.

How do we design effective and safe APIs?

The diagram below shows typical API designs with a shopping cart example.

TCP/IP encapsulation

How is data sent over the network? Why do we need so many layers in the OSI model? The diagram below shows how data is encapsulated and de-encapsulated when transmitting over the network.

• Step 1: When Device A sends data to Device B over the network via the HTTP protocol, it is first added an HTTP header at the application layer.
• Step 2: Then a TCP or a UDP header is added to the data. It is encapsulated into TCP segments at the transport layer. The header contains the source port, destination port, and sequence number.
• Step 3: The segments are then encapsulated with an IP header at the network layer. The IP header contains the source/destination IP addresses.
• Step 4: The IP datagram is added a MAC header at the data link layer, with source/destination MAC addresses.
• Step 5: The encapsulated frames are sent to the physical layer and sent over the network in binary bits.
• Steps 6-10: When Device B receives the bits from the network, it performs the de-encapsulation process, which is a reverse processing of the encapsulation process. The headers are removed layer by layer, and eventually, Device B can read the data.

We need layers in the network model because each layer focuses on its own responsibilities. Each layer can rely on the headers for processing instructions and does not need to know the meaning of the data from the last layer.

Why is Nginx called a “reverse” proxy?

A forward proxy is a server that sits between user devices and the internet. A forward proxy is commonly used for:

• Protecting clients
• Circumventing browsing restrictions
• Blocking access to certain content

A reverse proxy is a server that accepts a request from the client, forwards the request to web servers, and returns the results to the client as if the proxy server had processed the request. A reverse proxy is good for:

• Protecting servers
• Load balancing
• Caching static contents
• Encrypting and decrypting SSL communications

What are the common load-balancing algorithms?

The diagram below shows 6 common algorithms.

Static Algorithms

• Round robin

The client requests are sent to different service instances in sequential order. The services are usually required to be stateless.

• Sticky round-robin

This is an improvement of the round-robin algorithm. If Alice’s first request goes to service A, the following requests go to service A as well.

• Weighted round-robin

The admin can specify the weight for each service. The ones with a higher weight handle more requests than others.

• Hash

This algorithm applies a hash function on the incoming requests’ IP or URL. The requests are routed to relevant instances based on the hash function result.

Dynamic Algorithms

• Least connections

A new request is sent to the service instance with the least concurrent connections.

• Least response time

A new request is sent to the service instance with the fastest response time.

URL, URI, URN - Do you know the differences?

URI

URI stands for Uniform Resource Identifier. It identifies a logical or physical resource on the web. URL and URN are subtypes of URI. URL locates a resource, while URN names a resource. A URI is composed of the following parts: scheme:[//authority]path[?query][#fragment]

URL

URL stands for Uniform Resource Locator, the key concept of HTTP. It is the address of a unique resource on the web. It can be used with other protocols like FTP and JDBC.

URN

URN stands for Uniform Resource Name. It uses the urn scheme. URNs cannot be used to locate a resource. A simple example given in the diagram is composed of a namespace and a namespace-specific string.