What Is an API?

An API (Application Programming Interface) defines the boundary between software components—how they communicate, what operations are available, and what data formats are used.

API Paradigms

REST (Representational State Transfer)

REST is an architectural style for designing networked applications, defined by Roy Fielding in his 2000 doctoral dissertation.

REST API Design Principles

GET    /api/v1/users          # List users
GET    /api/v1/users/123      # Get user 123
POST   /api/v1/users          # Create user
PUT    /api/v1/users/123      # Replace user 123
PATCH  /api/v1/users/123      # Update user 123
DELETE /api/v1/users/123      # Delete user 123
GET    /api/v1/users/123/posts # List posts by user 123

REST Response Format

{
  "data": {
    "id": "123",
    "name": "Alice",
    "email": "alice@example.com",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:01Z"
  }
}

REST Pagination

{
  "data": [...],
  "pagination": {
    "total": 1250,
    "page": 3,
    "per_page": 20,
    "total_pages": 63,
    "next": "/api/v1/users?page=4&per_page=20",
    "prev": "/api/v1/users?page=2&per_page=20"
  }
}

GraphQL

GraphQL is a query language and runtime for APIs, developed by Facebook.

GraphQL vs REST

GraphQL Schema Example

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
}

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String): User!
  deleteUser(id: ID!): Boolean!
}

gRPC (Google Remote Procedure Call)

gRPC is a high-performance RPC framework using Protocol Buffers and HTTP/2.

gRPC Communication Patterns

Protocol Buffer Example

syntax = "proto3";

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
  rpc CreateUser (CreateUserRequest) returns (User);
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
}

message GetUserRequest {
  string id = 1;
}

Protocol Comparison

API Versioning

APIs evolve over time. Versioning strategies manage breaking changes.

Versioning Strategies

Rate Limiting

Rate limiting protects APIs from abuse and ensures fair resource usage.

Rate Limiting Algorithms

Rate Limit Response Headers

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 30

API Security

Authentication and Authorization

OAuth 2.0 Flows

Practice Exercises

1. Design: Design a RESTful API for a URL shortener. Include endpoints for creating, retrieving, and deleting short URLs, plus analytics. Consider rate limiting and versioning.

2. Compare: You're building a social media feed API. Compare REST, GraphQL, and gRPC for this use case. Which would you choose and why?

3. Implementation: Design a rate limiting strategy for an API that serves 10,000 requests/second. Which algorithm would you use? How would you handle distributed rate limiting across multiple servers?

4. Security: Design an authentication strategy for a system with three user types: anonymous readers, authenticated users, and admin users. How do you handle token refresh and revocation?

What to Learn Next