Integration Studies

What is REST?

REST (Representational State Transfer) is an architectural style for distributed hypermedia systems. It was defined by Roy Fielding in his 2000 doctoral dissertation.

Six Constraints of REST

• Client–Server: UI and data storage are separated, improving portability of the UI and scalability of the server.
• Stateless: Each request must contain all information needed to understand it. The server stores no client session state.
• Cacheable: Responses must define themselves as cacheable or non-cacheable. This improves scalability and performance.
• Uniform Interface: A consistent interface between components simplifies the architecture. Achieved via resource identification, manipulation through representations, self-descriptive messages, and HATEOAS.
• Layered System: A client cannot tell whether it connects directly to the end server or to an intermediary. Allows load balancers and gateways.
• Code on Demand (optional): Servers can extend client functionality by transferring executable code (e.g., JavaScript).

HTTP Methods

• GET – Retrieve a resource. Safe and idempotent.
• POST – Create a new resource or trigger an action. Not idempotent.
• PUT – Replace a resource entirely. Idempotent.
• PATCH – Partially update a resource. Idempotent.
• DELETE – Remove a resource. Idempotent.

Common HTTP Status Codes

• 200 OK – Success
• 201 Created – Resource was created (used with POST/PUT)
• 204 No Content – Success but no response body (used with DELETE)
• 400 Bad Request – Malformed request syntax
• 401 Unauthorized – Authentication required
• 403 Forbidden – Authenticated but not permitted
• 404 Not Found – Resource does not exist
• 409 Conflict – State conflict (e.g., duplicate)
• 422 Unprocessable Entity – Validation error
• 500 Internal Server Error – Unexpected server failure

Resource Naming

• Use nouns for resources, not verbs: `/orders` not `/getOrders`
• Use plural nouns: `/users`, `/products`, `/invoices`
• Use lowercase with hyphens for multi-word resources: `/order-items`
• Nest related resources: `/users/{id}/orders`

Versioning

Include the version in the URL path to allow breaking changes:

GET /api/v1/users
GET /api/v2/users

Alternatively, use request headers (`Accept: application/vnd.api+json;version=2`), but URL versioning is simpler to debug and cache.

Pagination

For large collections always paginate. Use query parameters:

GET /products?page=2&per_page=50

Include pagination metadata in the response:

{
  "data": [...],
  "meta": { "page": 2, "per_page": 50, "total": 1240 }
}

Error Handling

Return consistent error objects:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field is required.",
    "field": "email"
  }
}

Filtering, Sorting, and Searching

GET /products?category=electronics&sort=-price&q=laptop

• `sort=-price` means descending by price (minus prefix = descending)
• `q=laptop` is a full-text search term

What is a Message Broker?

A message broker is middleware that translates messages between formal messaging protocols. It decouples producers (senders) from consumers (receivers), enabling asynchronous communication and load levelling.

AMQP — Advanced Message Queuing Protocol

RabbitMQ implements AMQP 0-9-1. Key entities:

• Producer — an application that publishes messages.
• Exchange — receives messages from producers and routes them to queues based on rules.
• Binding — a rule that tells an exchange which queue(s) to route messages to.
• Queue — a buffer that stores messages until consumers process them.
• Consumer — an application that receives messages from a queue.

Exchange Types

Message Properties

• Delivery mode: 1 = transient (fast, lost on restart), 2 = persistent (written to disk)
• Content type: MIME type of the message body
• Expiration: TTL in milliseconds
• Priority: 0–255 (requires queue max-priority setting)

Acknowledgements

• Manual ack: consumer explicitly acks or nacks after processing. Prevents message loss.
• Auto ack: message is removed from queue as soon as delivered. Risk of data loss if consumer crashes mid-processing.

What is Apache Kafka?

Apache Kafka is a distributed event streaming platform designed for high-throughput, fault-tolerant, real-time data pipelines and event-driven architectures.

Core Concepts

• Event (Message): An immutable record of something that happened, containing a key, value, timestamp, and optional headers.
• Topic: A named log of events. Topics are append-only and ordered.
• Partition: A topic is split into partitions for parallelism. Each partition is an ordered, immutable sequence.
• Offset: A unique sequential ID for each message within a partition. Consumers track their position using offsets.
• Producer: An application that writes events to Kafka topics.
• Consumer: An application that reads events from topics.
• Consumer Group: A set of consumers that cooperate to consume a topic. Each partition is consumed by exactly one consumer in the group.
• Broker: A Kafka server. A Kafka cluster is composed of multiple brokers.
• Replication: Each partition is replicated across brokers for fault tolerance. One broker is the leader; others are followers.

Kafka vs RabbitMQ

Key Configuration Parameters

• `retention.ms`: how long messages are kept
• `replication.factor`: number of replicas per partition
• `min.insync.replicas`: minimum replicas that must acknowledge writes
• `auto.offset.reset`: earliest or latest — what to do when no committed offset exists