Resource-oriented architecture

API Design

Meaning

Resource-oriented architecture treats named, addressable resources as the primary abstraction for designing distributed systems, with each resource identified by a URI and manipulated through a uniform interface. It addresses the challenge of building scalable, evolvable APIs by making resources the unit of state and interaction rather than remote procedure calls. Developers reach for it when designing public APIs, web services, or any system where clients need to discover and manipulate entities across a network.

Primary Function

API design

Communicative Purpose

Enables scalable, evolvable distributed systems by making named resources the unit of state and interaction.

Pattern

identify resources → assign identifiers → define representations → expose uniform operations

Função primária

API design

Propósito comunicativo

Enables scalable, evolvable distributed systems by making named resources the unit of state and interaction.

Situações de gatilho

Web API design: structuring endpoints around resources rather than RPC-style operations

Contextos

REST APIs, microservices, web services, cloud platforms, distributed systems architecture

Padrão

identify resources → assign identifiers → define representations → expose uniform operations

Colocados típicos

REST
URI
HTTP methods
representation
hypermedia
HATEOAS
statelessness
uniform interface

Substituições comuns

RPC-style architecture: tight coupling
harder to evolve

Erros comuns

Confusing ROA with REST: REST is a specific HTTP-based instance; ROA is the broader style

Similar / contraste

REST: a specific HTTP-based instance of ROA

Interferências

Coming from OOP: may model resources as objects with methods — ROA emphasizes uniform operations on representations, not object methods

Família do chunk

REST
URI design
HATEOAS
uniform interface
representation design

Nuance

When NOT to use: high-frequency trading or real-time streaming where request-response overhead dominates

Efeito pragmático

Enables APIs that scale horizontally, evolve without breaking clients, and leverage HTTP caching and infrastructure.

Dica de memória

Resource-oriented architecture: think of the web itself — every page is a resource with an address, and you interact through a small set of verbs (GET, POST). The architecture mirrors what made the web successful.

Upgrade path

HATEOAS (Hypermedia as the Engine of Application State)

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

from flask import Flask, jsonify app = Flask(__name__) # Resource-oriented: customers is a resource collection @app.route('/customers/<int:customer_id>', methods=['GET']) def get_customer(customer_id): customer = db.get_customer(customer_id) return jsonify({ "id": customer.id, "name": customer.name, "email": customer.email, "_links": [ {"rel": "orders", "href": f"/customers/{customer_id}/orders"} ] })

# Order service owns the orders resource as its primary abstraction class OrderService: def get_order(self, order_id): return self.repository.find(order_id) def create_order(self, representation): order = Order.from_representation(representation) return self.repository.save(order)

def order_representation(order): return { "id": order.id, "status": order.status, "total": order.total, "_links": { "self": {"href": f"/orders/{order.id}"}, "cancel": {"href": f"/orders/{order.id}/cancel", "method": "POST"}, "customer": {"href": f"/customers/{order.customer_id}"} } }