Eventually Bitwise

API Design

Overview

API (Application Programming Interface) design is the process of creating a set of rules and protocols that allow different software components to communicate with each other. A well-designed API is intuitive, maintainable, and scalable.

Core Concepts

  • REST (Representational State Transfer):
    • Statelessness: Each request from a client to server must contain all the information to understand and complete the request.
    • Resource-Based: Everything is a resource, identified by a URI (e.g., /users/123).
    • Standard HTTP Methods: GET (read), POST (create), PUT (update), DELETE (remove).
    • HATEOAS: Hypermedia as the Engine of Application State (providing links to related resources in the response).
  • GraphQL:
    • Single Endpoint: All requests go to one endpoint (usually /graphql).
    • Client-Specified Data: Clients request exactly the data they need, solving “over-fetching” and “under-fetching”.
    • Schema-Driven: Uses a strongly typed schema to define queries and mutations.
  • gRPC (Google Remote Procedure Call):
    • Protocol Buffers: Uses binary serialization (Protobuf) instead of JSON for high performance.
    • HTTP/2: Leverages HTTP/2 for streaming and multiplexing.
    • Strongly Typed: Defined via .proto files.
  • API Versioning: Managing changes without breaking existing clients (e.g., /v1/, /v2/).

Code Examples

// Conceptual REST endpoint definition
app.get('/users/:id', (req, res) => {
    const userId = req.params.id;
    const user = db.findUser(userId);
    if (!user) return res.status(404).send("User not found");
    res.json(user);
});

// Conceptual GraphQL query
const query = `
  query {
    user(id: "123") {
      name
      email
      posts {
        title
      }
    }
  }
`;

Use Cases

  • Frontend-Backend Communication: Connecting a React/Angular app to a Node/Python backend.
  • Third-Party Integrations: Allowing other companies to build on top of your platform (e.g., Stripe, Twilio).
  • Internal Microservices: Communication between different services in a distributed system.

Gotchas

  • Breaking Changes: Changing a field name or removing an endpoint without versioning.
  • Over-fetching: REST often returns more data than the client actually needs.
  • Security: Failing to implement proper authentication (OAuth2, JWT) and rate limiting.

Related Notes

, ,