A Developer’s Dilemma

Ankit was building a mobile app for a food delivery service. He needed an API to fetch restaurant details, place orders, and update delivery status.

He started with REST, but fetching related data required multiple calls. He considered GraphQL but wasn’t sure if it was worth the complexity. Then, he heard about tRPC and OpenAPI, then he thought better to read this article to learn more and better.

Choosing the right API design was critical for performance, scalability, and ease of development.

What is API Design?

API design defines how different software components communicate. It ensures:

• Consistency – Uniform request and response structures.

• Scalability – Efficient handling of growing traffic.

• Security – Protecting data with authentication and authorization.

A well-designed API makes it easier for developers to build and maintain applications.

Understanding API Architectures

1. REST (Representational State Transfer)

REST is the most widely used API architecture. It follows these principles:

• Uses stateless HTTP requests.

• Uses standard HTTP methods – GET, POST, PUT, DELETE.

• Data is exchanged in JSON or XML.

Example REST API request:

GET /users/1
Response: { "id": 1, "name": "Emma" }

✔ Simple and easy to implement. ✔ Well-supported with existing libraries. ✔ Scalable due to stateless nature.

✖ Over-fetching or under-fetching of data. ✖ Multiple requests needed for related data.

2. GraphQL – Flexible Data Fetching

GraphQL allows clients to request only the data they need, reducing unnecessary network calls.

Example GraphQL query:

query {
  user(id: 1) {
    name
    email
  }
}

✔ Fetch multiple resources in a single request. ✔ Reduces over-fetching and under-fetching. ✔ Strongly typed schema for predictable results.

✖ More complex than REST. ✖ Requires additional server processing.

Here, client simply asks for what it wants and server only delivers that. Assume user model is having user's name, email, phone, address, interests, hobbies, etc. But on app's main page, we do want to display only name and email, then we can fetch only those, whereas on profile page, all details can be shown.

3. tRPC – Type-Safe API for TypeScript

tRPC (TypeScript Remote Procedure Call) enables type-safe API communication without needing a separate schema.

• End-to-end type safety – Both frontend and backend share types.

• No need for REST routes or GraphQL resolvers.

• Minimal boilerplate code.

Example tRPC request:

const user = await trpc.user.get({ id: 1 });
console.log(user.name);

✔ Best suited for TypeScript-based applications. ✔ No need to write API schemas separately. ✔ Lightweight and efficient.

✖ Limited adoption compared to REST and GraphQL. ✖ Best suited for TypeScript projects only.

4. OpenAPI – Standardized API Documentation

OpenAPI is not an API architecture but a specification for designing and documenting APIs.

• Provides a standardized way to describe RESTful APIs.

• Enables automatic API documentation.

• Supports tools like Swagger for visualizing APIs.

Example OpenAPI definition:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      responses:
        200:
          description: Success

✔ Improves API discoverability and documentation. ✔ Helps generate client SDKs automatically. ✔ Makes API testing and validation easier.

✖ Does not define how the API behaves. ✖ Only useful for documentation purposes.

A Beautiful swagger documentation can be generated using this, like here:

Choosing the Right API Architecture

Feature

REST

GraphQL

tRPC

OpenAPI

Simplicity

✔✔✔

✔✔

✔✔

N/A

Flexibility

✔

✔✔✔

✔✔

N/A

Performance

✔✔

✔✔

✔✔✔

N/A

Type Safety

✖

✔✔

✔✔✔

✔

When to Use Each API:

• Use REST if you need a simple, widely supported API.

• Use GraphQL if you need flexible data fetching.

• Use tRPC if you work with TypeScript and want type safety.

• Use OpenAPI if you need auto-generated documentation.

Real-World Use Cases

1. E-Commerce Platforms

• REST APIs for product listings and user authentication.

• GraphQL for personalized product recommendations.

• OpenAPI for auto-generating API documentation.

2. Social Media Apps

• GraphQL for fetching posts and comments efficiently.

• REST APIs for login and authentication.

• WebSockets for real-time notifications.

3. FinTech Applications

• REST APIs for handling transactions.

• OpenAPI for exposing banking APIs securely.

Conclusion

Choosing the right API design depends on your use case.

REST remains the most common, but GraphQL offers more flexibility. tRPC is great for TypeScript projects, and OpenAPI ensures good documentation.

In the next article, we’ll explore Load Balancing Techniques – Round Robin, Least Connections, Consistent Hashing.

Powered by Synscribe