resource identification

API Design

Meaning

Resource identification is the process of defining and naming the addressable entities in a system so each can be uniquely referenced. It addresses the pain point of ambiguity in distributed systems where clients and servers must agree on what is being acted upon. It is triggered when designing APIs, modeling domains, or provisioning infrastructure where stable, unique references to entities are required.

Primary Function

API design

Communicative Purpose

Ensures every addressable entity in a system has a stable, unique, noun-based identifier that clients can use to locate and interact with it.

Pattern

identify noun-based entities → assign unique URIs/IDs → expose via standard operations

Função primária

API design

Propósito comunicativo

Ensures every addressable entity in a system has a stable, unique, noun-based identifier that clients can use to locate and interact with it.

Situações de gatilho

REST API design: naming collections and items with URIs before exposing endpoints System architecture: distinguishing persistent resources from transient actions during service decomposition Cloud infrastructure: tagging and addressing compute, storage, or IAM resources via ARNs or resource IDs

Contextos

REST API design, microservices, cloud platforms (AWS, Azure, GCP), domain-driven design, web services, database schema modeling

Padrão

identify noun-based entities → assign unique URIs/IDs → expose via standard operations

Colocados típicos

URI
REST
CRUD
endpoint design
noun-based modeling
resource hierarchy
collection resource
item resource

Substituições comuns

RPC-style verb endpoints (e.g.
/getUser) — less RESTful and harder to cache
opaque UUIDs vs semantic slugs — trade readability for unpredictability

Erros comuns

Using verbs in resource URIs like /getUser instead of /users/{id} — violates REST noun-based modeling and breaks caching assumptions. Mixing collection and item semantics in one URI like /users/list — conflates two distinct resource types. Embedding transport or storage details like /users/mysql/1 — couples the API surface to implementation and blocks refactors. Inconsistent pluralization across endpoints — fragments the API and confuses client generators. Forgetting that actions are not resources — trying to model /sendEmail as a resource instead of a POST to /emails.

Similar / contraste

Resource vs Action: resources are addressable nouns; actions are non-addressable verbs. Resource identification vs Authentication: identification names the entity; authentication controls who may access it. URI vs URL: a URI identifies a resource abstractly; a URL additionally specifies how to locate it.

Interferências

Coming from RPC/SOAP: may default to verb-based endpoints (getUser, doSearch) — REST resource identification requires noun-based URIs and standard methods. Coming from OOP: may treat class instances as REST resources directly — resources must be addressable via URIs and decoupled from in-memory representation. Coming from filesystem paths: may over-nest URIs (/org/team/user/1) — shallow hierarchies with query params are usually more flexible.

Família do chunk

REST architectural constraints
URI design
resource modeling
CRUD-to-HTTP mapping
Richardson Maturity Model

Nuance

When NOT to use: for purely transient operations with no persistent state (e.g., /calculate, /translate) where modeling a resource adds no value. Performance: deep URI hierarchies increase routing table size and can complicate CDN cache-key design. Boundary condition: composite resources like /users/{id}/orders are valid but should reflect genuine ownership, not arbitrary nesting.

Efeito pragmático

Produces predictable, self-describing APIs that integrate cleanly with caching layers, documentation generators, and hypermedia clients, while keeping the contract stable across server refactors.

Dica de memória

Resource identification is like assigning a unique postal address to every parcel in a warehouse — once each thing has a stable address, any worker can find it without asking.

Upgrade path

HATEOAS and hypermedia-driven resource discovery (Richardson Maturity Model Level 3)

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

Examples

# REST resource identification with Flask from flask import Flask, jsonify app = Flask(__name__) @app.route('/api/users/<int:user_id>', methods=['GET']) def get_user(user_id): user = {'id': user_id, 'name': 'Ada Lovelace', 'email': 'ada@example.com'} return jsonify(user) if __name__ == '__main__': app.run()

# Cloud resource identification via ARN parsing def parse_arn(arn): parts = arn.split(':', 5) return { 'service': parts[2], 'region': parts[3], 'account': parts[4], 'resource': parts[5], } bucket_arn = 'arn:aws:s3:::prod-artifacts/reports/2024/q4.pdf' print(parse_arn(bucket_arn)) # {'service': 's3', 'region': '', 'account': '', 'resource': 'prod-artifacts/reports/2024/q4.pdf'}

# Resource identification in a domain model class ResourceRegistry: def __init__(self): self._resources = {} def register(self, resource_type, identifier, attributes): if resource_type not in self._resources: self._resources[resource_type] = {} self._resources[resource_type][identifier] = attributes def resolve(self, resource_type, identifier): return self._resources[resource_type][identifier] registry = ResourceRegistry() registry.register('order', 'ord_1001', {'total': 249.99, 'status': 'shipped'}) print(registry.resolve('order', 'ord_1001'))