Lecture 3: What Are APIs and How Are They Used?

APIs are the dominant mechanism for integrating modern software systems. Understanding what an API is, the different styles available, and how to use them well is foundational knowledge for anyone working with system integrations. This lecture covers APIs from definition through to design principles, versioning, and the role of API management in enterprise architecture.

What Is an API?

An API (Application Programming Interface) is a defined contract that specifies how software components can interact. An API says:

Here are the operations you can request
Here is how you format a request
Here is what you will get back

The word "interface" is key. An API separates what a system does (its implementation) from how others interact with it (its contract). The consumer does not need to know how the system works internally — only what the API offers.

APIs Are Everywhere

APIs are not just web services. They exist at every layer of software:

Operating system APIs — how applications request file I/O, memory, or network from the OS
Library APIs — how your code calls functions in a library (e.g., Math.sqrt())
Database APIs — how applications send SQL queries to a database
Web service APIs — how systems communicate over a network (HTTP, AMQP, gRPC)

In integration contexts, "API" most commonly refers to web service APIs — interfaces exposed over a network that allow one system to request data or trigger actions in another.

REST APIs

REST (Representational State Transfer) is the dominant API style for web and cloud integration. It uses HTTP as its transport protocol and treats everything as a resource addressable by a URL.

Core REST Concepts

Resource: anything that can be named and addressed — an order, a customer, an invoice.

URL: the address of a resource:

https://api.example.com/orders          → the collection of all orders
https://api.example.com/orders/1234     → a specific order
https://api.example.com/customers/99/orders → orders for customer 99

HTTP Methods: the operations you can perform on a resource:

GET — retrieve a resource (read-only, safe to repeat)
POST — create a new resource
PUT — replace a resource entirely
PATCH — partially update a resource
DELETE — remove a resource

Representation: the format of the resource in the response — almost always JSON for modern REST APIs.

REST Request and Response Example

HTTP

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

{
  "customerId": "CUST-99",
  "items": [
    { "productId": "PROD-A", "quantity": 2 }
  ]
}

HTTP/1.1 201 Created
Location: /orders/1234
Content-Type: application/json

{
  "orderId": "1234",
  "status": "pending",
  "createdAt": "2026-04-18T10:30:00Z"
}

REST Characteristics

Stateless: each request contains all information needed to process it. The server does not retain session state between requests.

Uniform interface: all resources follow the same URL and method conventions.

Client-server separation: the client and server evolve independently. The client only needs to know the API contract, not the server implementation.

REST Status Codes

Status codes communicate the result of a request:

2xx Success:    200 OK, 201 Created, 204 No Content
4xx Client error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation Error
5xx Server error: 500 Internal Server Error, 503 Service Unavailable

A 4xx error means the client sent a bad request — fix the request. A 5xx error means the server failed — try again later.

SOAP APIs

SOAP (Simple Object Access Protocol) is an older, more structured API style that uses XML for message format and typically runs over HTTP.

XML

POST /OrderService HTTP/1.1
Content-Type: text/xml

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetOrder>
      <OrderId>1234</OrderId>
    </GetOrder>
  </soap:Body>
</soap:Envelope>

SOAP Characteristics

Contract-first: SOAP services are defined by a WSDL (Web Services Description Language) file that describes every operation, its inputs, and its outputs. Clients generate code from the WSDL.

Strong typing: all messages are validated against an XML schema.

Built-in standards: WS-Security for authentication/encryption, WS-ReliableMessaging for delivery guarantees, WS-AtomicTransaction for distributed transactions.

Verbose: XML is more verbose than JSON, leading to larger message sizes.

When SOAP Is Used

SOAP remains common in:

Banking and financial services (SWIFT, payment processing)
Healthcare (HL7 SOAP services, insurance claims)
Government and public sector
Legacy enterprise systems (SAP, Oracle ERP) that pre-date REST

GraphQL

GraphQL is a query language for APIs where the client specifies exactly what data it needs in a single request.

GRAPHQL

query {
  order(id: "1234") {
    orderId
    status
    customer {
      name
      email
    }
    items {
      productName
      quantity
    }
  }
}

The server returns only the requested fields — no more, no less.

GraphQL vs. REST

| Aspect | REST | GraphQL | |--------|------|---------| | Data fetching | Fixed response shape | Client specifies exact fields | | Over-fetching | Common — returns all fields | Eliminated | | Under-fetching | Multiple requests for related data | Single query can span relations | | Schema | Implicit (documented separately) | Explicit, strongly typed schema | | Caching | Easy (URL-based HTTP caching) | More complex (POST-based) | | Best for | Simple, public APIs | Complex data needs, multiple clients |

When to Use GraphQL

GraphQL is particularly well-suited when:

Multiple clients (mobile, web, desktop) have different data shape requirements
Reducing the number of network round-trips is critical (mobile apps with limited bandwidth)
The data model is richly relational and clients need to navigate those relations flexibly

gRPC

gRPC is a high-performance, binary RPC framework developed by Google. It uses HTTP/2 as transport and Protocol Buffers (Protobuf) as the message format.

PROTOBUF

// Service definition
service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);
  rpc StreamOrders (OrderFilter) returns (stream Order);
}

message Order {
  string order_id = 1;
  string status = 2;
  double total_amount = 3;
}

gRPC Characteristics

Binary protocol: much more compact than JSON or XML — lower bandwidth, faster serialisation.

Strongly typed: the .proto schema is the contract; clients and servers generate type-safe code in any supported language.

Streaming: supports server-side, client-side, and bidirectional streaming — not possible with standard REST.

Code generation: client and server code is generated from the .proto file, eliminating manual serialisation.

When to Use gRPC

Internal microservice-to-microservice communication
Performance-critical APIs (high throughput, low latency)
Polyglot systems (multiple languages sharing the same contract)
Streaming use cases (real-time data feeds, bidirectional communication)

API Design Principles

Design for the Consumer

An API is a product consumed by developers. Design for their experience:

Use predictable, consistent naming conventions
Return useful error messages that tell the consumer what went wrong
Provide complete documentation with examples
Be stable — avoid breaking changes without a long deprecation period

Keep It Simple

Expose only what consumers actually need. A smaller, cleaner API is easier to understand, document, and maintain than a large one that exposes every internal capability.

Resource-Oriented Design (for REST)

Name resources as nouns, not verbs:

Good: POST /orders        (create an order)
Bad:  POST /createOrder   (action-based naming)

Group related resources under a common path:

/customers/{id}
/customers/{id}/orders
/customers/{id}/addresses

Pagination

Never return unbounded collections. Implement pagination for any endpoint that returns a list:

JSON

GET /orders?page=2&size=20

{
  "items": [...],
  "page": 2,
  "pageSize": 20,
  "totalCount": 487,
  "totalPages": 25
}

Error Responses

Always return structured error responses — never just an HTTP status code with an empty body:

JSON

{
  "type": "validation-error",
  "title": "Request validation failed",
  "status": 422,
  "errors": [
    { "field": "customerId", "message": "Customer not found" }
  ]
}

API Versioning

APIs change over time, but consumers depend on stability. Versioning allows the API to evolve without breaking existing consumers.

URI Versioning (most common)

/api/v1/orders
/api/v2/orders

When you make a breaking change, increment the version. Maintain the old version for a deprecation period.

What Is a Breaking Change?

| Change | Breaking? | |--------|-----------| | Add optional field to response | No | | Add new endpoint | No | | Remove a field | Yes | | Rename a field | Yes | | Change field type | Yes | | Change HTTP method | Yes | | Make optional field required | Yes |

Deprecation Policy

Before removing a version:

Announce the deprecation with a target removal date
Add a Deprecation header to responses from the old version
Monitor which consumers are still using the old version
Provide migration guidance

API Documentation

Good API documentation is essential for adoption. Tools:

OpenAPI Specification (formerly Swagger): the industry standard for documenting REST APIs. Describes endpoints, parameters, request/response schemas, and authentication in a machine-readable YAML or JSON file.

Swagger UI / Redoc: auto-generate interactive documentation from an OpenAPI spec. Developers can read docs and test endpoints in the browser.

Postman: a tool for testing APIs and sharing collections of example requests.

An OpenAPI spec can also be used to:

Generate client SDKs in multiple programming languages
Generate server stubs
Validate requests in tests and in CI pipelines

API Gateway

An API gateway is a server that sits in front of your APIs and handles cross-cutting concerns:

Client ──► API Gateway ──► Service A
                       ──► Service B
                       ──► Service C

What an API gateway does:

| Function | Description | |----------|-------------| | Authentication | Validates tokens, API keys, or certificates | | Authorisation | Checks scopes and permissions | | Rate limiting | Limits requests per client per time window | | Request routing | Routes requests to the correct backend service | | Request/response transformation | Modifies headers, translates protocols | | Caching | Caches responses to reduce backend load | | Logging and analytics | Captures metrics on API usage | | SSL termination | Handles HTTPS so backend services don't need to |

Examples: Azure API Management, AWS API Gateway, Kong, Apigee, NGINX.

APIs in Enterprise Integration Strategy

Internal APIs (Private)

APIs used only within the organisation's own systems. Higher trust, can be less formal, but still need versioning and documentation.

Partner APIs (Protected)

APIs shared with trusted business partners. Require authentication (API keys or OAuth), rate limiting, and a partner agreement. Less public than public APIs but still need stability.

Public APIs (Open)

APIs open to any developer. Require complete documentation, strong security, rate limiting, and a stable versioning policy. Examples: Google Maps API, Twitter API, Stripe API.

API Products

Modern organisations treat APIs as products — with product owners, roadmaps, SLAs, and developer portals. The API product bundles the technical API with documentation, SDKs, sandbox environments, and usage analytics.

Lecture 3 Summary

An API is a contract that defines how software components interact — separating what a system does from how others call it.
REST is the dominant web API style: URL-addressable resources, HTTP verbs, JSON payloads, stateless.
SOAP is an older, contract-first (WSDL), XML-based style still common in financial and healthcare systems.
GraphQL gives clients control over the data shape they receive — ideal for multiple clients with different needs.
gRPC is a high-performance binary protocol using HTTP/2 and Protobuf — best for internal microservice communication.
Design APIs for consumers: consistent naming, pagination, structured errors, full documentation.
Version APIs to allow evolution without breaking consumers; define clearly what constitutes a breaking change.
API gateways handle authentication, authorisation, rate limiting, routing, and logging in one place.

Next: Lecture 4 — System Integration Design Principles