APIs & Web Services on Software Engineering Learning Paths

REST Principles

Mon, 01 Jan 0001 00:00:00 +0000

REST Principles#

REST (Representational State Transfer) is an architectural style defined by Roy Fielding in his 2000 doctoral dissertation. It describes a set of constraints that, when applied to web services, yield systems that are scalable, loosely coupled, and simple to understand.

The Six REST Constraints#

REST is not a protocol or a standard — it’s a set of architectural constraints. A service that satisfies all constraints is called RESTful.

API Design

Mon, 01 Jan 0001 00:00:00 +0000

API Design#

Good API design makes the right thing easy and the wrong thing hard. This section covers the practical patterns for URL structure, request/response shaping, pagination, error handling, and bulk operations that production APIs rely on.

URL Structure#

A well-designed URL is predictable, readable, and consistent.

Anatomy of an API URL#

https://api.example.com/v1/customers/42/orders?status=shipped&page=2
└─────────┬──────────┘ └┬┘ └────┬────┘ └┘ └──┬──┘ └──────┬───────┘
 base URL ver collection id sub-res query params

Design Rules#

Rule	Good	Bad
Use nouns for resources	`/invoices`	`/getInvoices`
Plural for collections	`/users`	`/user`
IDs in path for specifics	`/users/42`	`/users?id=42`
Nest for relationships	`/users/42/posts`	`/posts?user_id=42` (acceptable for filtering)
Max 2 levels of nesting	`/users/42/posts`	`/users/42/posts/7/comments/3/likes`
Actions as sub-resources	`/orders/42/cancel`	`/cancelOrder?id=42`
Consistent naming	`snake_case` or `camelCase` (pick one)	Mixing conventions

When Nesting Gets Too Deep#

If you need more than two levels, flatten:

Authentication & Authorization

Mon, 01 Jan 0001 00:00:00 +0000

Authentication & Authorization#

Authentication (AuthN) verifies who you are. Authorization (AuthZ) determines what you can do. Every API needs both. This section covers the mechanisms from simple API keys to full OAuth2 flows.

Authentication vs Authorization#

Aspect	Authentication (AuthN)	Authorization (AuthZ)
Question	“Who is this?”	“Can they do this?”
Happens	First	After authentication
Mechanism	Credentials, tokens	Permissions, roles, policies
Failure code	401 Unauthorized	403 Forbidden

sequenceDiagram
 participant Client
 participant API
 participant AuthServer

 Client->>API: Request with credentials
 API->>AuthServer: Validate credentials (AuthN)
 AuthServer-->>API: Identity confirmed
 API->>API: Check permissions (AuthZ)
 API-->>Client: 200 OK or 403 Forbidden

API Keys#

The simplest authentication mechanism. A long, random string shared between client and server.

OpenAPI & Documentation

Mon, 01 Jan 0001 00:00:00 +0000

OpenAPI & Documentation#

A well-documented API is a usable API. The OpenAPI Specification (formerly Swagger) provides a machine-readable description of your API that powers documentation, code generation, testing, and validation.

What is OpenAPI?#

OpenAPI is a standard for describing REST APIs. It’s a YAML or JSON document that describes every endpoint, parameter, request body, response, and authentication mechanism your API offers.

OpenAPI Document Structure#

openapi: 3.1.0
info:
 title: Orders API
 description: API for managing customer orders
 version: 1.2.0
 contact:
 name: Platform Team
 email: platform@example.com

servers:
 - url: https://api.example.com/v1
 description: Production
 - url: https://staging-api.example.com/v1
 description: Staging

paths:
 /orders:
 get: ...
 post: ...
 /orders/{id}:
 get: ...
 put: ...
 delete: ...

components:
 schemas: ...
 securitySchemes: ...

security:
 - bearerAuth: []

Key Sections#

Section	Purpose	Contains
`info`	API metadata	Title, version, description, contact
`servers`	Base URLs	Production, staging, dev environments
`paths`	Endpoints	All routes with operations
`components`	Reusable definitions	Schemas, parameters, security, responses
`security`	Global auth requirements	Default security schemes
`tags`	Grouping	Logical grouping of operations

Schema Definition#

Schemas define the shape of request and response bodies:

Versioning & Evolution

Mon, 01 Jan 0001 00:00:00 +0000

Versioning & Evolution#

APIs evolve. New features arrive, old patterns prove inadequate, business requirements shift. The challenge is evolving your API without breaking existing consumers. This section covers versioning strategies, change classification, and lifecycle management.

Why Version?#

Once an API has consumers, you can’t freely change it. Versioning gives you a mechanism to:

Introduce breaking changes without disrupting existing clients
Communicate the stability of different API surfaces
Allow consumers to migrate at their own pace
Maintain multiple versions during transition periods

Versioning Strategies#

URL Path Versioning#

The most common and visible approach. The version is part of the URL:

Rate Limiting & Throttling

Mon, 01 Jan 0001 00:00:00 +0000

Rate Limiting & Throttling#

Rate limiting protects APIs from abuse, ensures fair resource allocation, and maintains service stability under heavy load. Understanding rate limiting algorithms and their trade-offs is essential for both API providers and consumers.

Why Rate Limit?#

Protect infrastructure from overload and cascading failures
Ensure fairness among consumers sharing a service
Prevent abuse (scraping, brute-force attacks, DDoS)
Control costs for metered or pay-per-use services
Meet SLAs by preserving capacity for critical traffic

Rate Limiting Algorithms#

Token Bucket#

The token bucket algorithm allows bursts while enforcing an average rate. Tokens are added to a bucket at a fixed rate; each request consumes one token. If the bucket is empty, the request is rejected.

GraphQL

Mon, 01 Jan 0001 00:00:00 +0000

GraphQL#

GraphQL is a query language for APIs and a runtime for executing those queries. Unlike REST, it lets clients request exactly the data they need in a single request, eliminating over-fetching and under-fetching.

Core Concepts#

Concept	Description
Schema	Defines the types, queries, mutations, and subscriptions available
Query	Read operation — fetches data
Mutation	Write operation — creates, updates, or deletes data
Subscription	Real-time operation — pushes data to clients via WebSocket
Resolver	Function that fetches the data for a specific field
Type	Defines the shape of data (object, scalar, enum, interface, union)

Schema Definition Language (SDL)#

Scalar Types#

GraphQL has five built-in scalars: Int, Float, String, Boolean, ID.

Webhooks & Async APIs

Mon, 01 Jan 0001 00:00:00 +0000

Webhooks & Async APIs#

Not all API communication follows the request-response pattern. Webhooks, polling, callbacks, and WebSockets enable asynchronous, event-driven architectures where systems react to changes as they happen rather than repeatedly asking “has anything changed?”

Webhooks#

A webhook is a user-defined HTTP callback. When an event occurs in the source system, it sends an HTTP POST to a URL configured by the consumer.

How Webhooks Work#

┌──────────┐ 1. Register URL ┌──────────────┐
│ Client │ ────────────────────── │ Provider │
│ (Server) │ │ (e.g. Stripe│
│ │ ◄───────────────────── │ GitHub) │
└──────────┘ 2. POST event data └──────────────┘

Consumer registers a callback URL with the provider
An event occurs in the provider (payment completed, PR merged, etc.)
Provider sends an HTTP POST with event payload to the registered URL
Consumer processes the event and returns 2xx to acknowledge

Webhook Payload Design#

{
 "id": "evt_1NqB6e2eZvKY",
 "type": "payment.completed",
 "created": "2024-01-15T10:30:00Z",
 "data": {
 "object": {
 "id": "pay_abc123",
 "amount": 2500,
 "currency": "eur",
 "status": "succeeded"
 }
 },
 "api_version": "2024-01-01"
}

Best practices for payloads:

gRPC & Binary Protocols

Mon, 01 Jan 0001 00:00:00 +0000

gRPC & Binary Protocols#

REST with JSON dominates public APIs, but service-to-service communication benefits from binary protocols — smaller payloads, schema enforcement, and code generation. gRPC is the industry standard for internal microservice communication.

Why Binary Protocols?#

	REST + JSON	gRPC + Protobuf
Encoding	Text (UTF-8 JSON)	Binary (Protocol Buffers)
Payload size	Larger (~2-10×)	Smaller
Schema	Optional (OpenAPI)	Required (.proto files)
Code generation	Optional	Built-in (every language)
Streaming	Workarounds (SSE, WebSocket)	Native (4 streaming modes)
Browser support	Native	Requires gRPC-Web proxy
Human-readable	Yes	No (binary wire format)
Type safety	Runtime validation	Compile-time from .proto
Transport	HTTP/1.1 or HTTP/2	HTTP/2 (required)

Protocol Buffers (Protobuf)#

The serialisation format used by gRPC: