API Design & GraphQL
REST best practices and the GraphQL alternative
IT & Tech Reports | Class IM24A | 2026
1. REST API Design Principles (Review)
• Resources should be nouns, not verbs: /orders not /createOrder
• Use HTTP methods semantically: GET (safe, idempotent), POST (not idempotent), PUT/PATCH,
DELETE
• Return appropriate status codes — 201 for creation, 204 for deletion, 422 for validation errors
• Version your API from day one: /api/v1/ — never break existing clients
• Use consistent pagination: cursor-based for large datasets, offset for small ones
2. OpenAPI / Swagger
OpenAPI (formerly Swagger) is the standard for documenting REST APIs. A machine-readable
YAML/JSON spec enables auto-generated docs, client SDKs, and mock servers.
openapi: "3.1.0"
info:
title: Games API
version: "1.0.0"
paths:
/games/{id}:
get:
summary: Get a game by ID
parameters:
- name: id
in: path
required: true
schema: { type: integer }
responses:
"200":
description: Game found
content:
application/json:
schema: { $ref: "#/components/schemas/Game" }
"404": { description: Game not found }
3. What is GraphQL?
GraphQL is a query language for APIs and a runtime for executing queries, developed by Facebook in
2012. Unlike REST, clients specify exactly what data they need in a single request — no over-fetching
or under-fetching.
REST GraphQL
Endpoints Multiple (/users, /posts, ...) Single endpoint (/graphql)
Data shape Fixed by server Client specifies exact fields
Over-fetching Common Eliminated
Under-fetching Requires multiple requests Single request with nested queries
Type system Via OpenAPI (optional) Built-in, strongly typed schema
Real-time WebSockets / polling Built-in subscriptions
Caching HTTP cache (easy) Requires client-side cache (Apollo)
4. GraphQL Query Examples
# Query — fetch exactly what you need
query GetGame($id: ID!) {
game(id: $id) {
title
releaseYear
studio {
name
country
genres
# Mutation — create/update data
mutation CreateGame($input: GameInput!) {
createGame(input: $input) {
id
title
# Subscription — real-time updates
subscription OnNewGame {
gameAdded {
id
title
}
5. GraphQL Schema Definition Language (SDL)
type Game {
id: ID!
title: String!
releaseYear: Int
genres: [String!]!
studio: Studio
type Studio {
id: ID!
name: String!
country: String
games: [Game!]!
type Query {
game(id: ID!): Game
games(genre: String, limit: Int): [Game!]!
type Mutation {
createGame(input: GameInput!): Game!
deleteGame(id: ID!): Boolean!
6. API Gateways
An API gateway sits in front of microservices and handles cross-cutting concerns:
• Authentication & authorisation — verify JWT/OAuth before requests reach services
• Rate limiting — throttle requests per client/API key
• Request routing — path-based routing to different backend services
• Load balancing — distribute traffic across service instances
• Caching — cache responses at the gateway level
• Observability — centralised logging, tracing, and metrics collection
Gateway Type Notes
Kong OSS/Cloud Plugin-based, highly extensible, Lua/Go plugins
Gateway Type Notes
AWS API Gateway Managed Tight AWS integration, Lambda triggers
Traefik OSS Cloud-native, automatic service discovery in K8s
Nginx OSS High-performance reverse proxy — simple and battle-tested