If you've ever stored a URL in a database and later regretted it, this is for you.
It's a familiar scenario: a service needs to keep a reference to a resource that lives in another service. The obvious solution is to store the URL. It works — until the host changes, the API gets a new version, or the team decides to restructure the paths. Suddenly all the stored references are broken, and tracking down the impact becomes a bigger problem than it should be.
The root issue is that a URL mixes two different things: what the resource is and where it lives. When you store a URL, you're betting that location won't change. In systems that evolve, that's usually a losing bet.
The idea
What if instead of storing where the resource lives, you store your own identifier that a gateway knows how to resolve?
commerce:orders/order:id=ARG-2024-00091872
finance:accounts/customer:status:id=109234
health:coverage/credential:patient-id=12345678
Whoever stores the reference doesn't need to know where the resource lives or how to access it. That's the gateway's responsibility. If the API changes, if the service migrates, if a new system appears: only the resolver changes. The stored references remain valid.
I called this scheme Delegated Resource Identifier (DRI).
What this pattern is not
- It's not a standard
- It requires a gateway as intermediary: it doesn't apply when the client needs to access the resource directly without going through any intermediary
- It doesn't impose a context taxonomy: each team defines their own
It's a useful convention when you need persistent references to resources in a controlled ecosystem and want to centralize the resolution logic.
How it's built
The identifier has two parts separated by /:
<context>/<resource>
- Context (left side): identifies the domain that knows how to resolve this type of resource. The gateway uses it for routing.
- Resource (right side): identifies the concrete resource. Its structure is defined by whoever implements the resolver.
commerce:orders/order:id=ARG-2024-00091872
└─── routing ───┘└─── concrete resource ──┘
: separates hierarchical levels. = assigns values. Each side defines its own internal convention.
The identifier is built by whoever stores the reference, from the data they already have and the context they know. No external call required. A billing service that receives an order ID knows it belongs to commerce:orders and builds the DRI when persisting the reference.
The context can be omitted if the gateway has a default resolver:
/order:id=ARG-2024-00091872
Some use cases
E-commerce: retrieving an order
A customer service system stores references to orders that can come from different channels: own store, marketplace, mobile app. Each channel has its own API.
commerce:orders/order:id=ARG-2024-00091872
commerce:orders/order:id=MKT-2024-00034521
The commerce:orders resolver determines which channel each order belongs to based on the ID prefix and routes to the corresponding API. The identifier remains stable even if the channel's API changes.
Fintech: customer account status
A bank with legacy and modern systems running side by side. The resolver determines which system the customer lives in based on the ID value: customers with id < 50000 are in the legacy system, the rest in the modern one.
finance:accounts/customer:status:id=109234
finance:accounts/customer:status:id=002871
The resolver also encapsulates the decision of which API version to use. And here something interesting emerges: the DRI has two moments in its lifecycle. When persisted, it's just the identifier. When used for a query, it can be enriched with additional context using the same syntax:
finance:accounts/customer:status:id=109234:date=20260101
The resolver can use that date to determine which API version applies. The persisted DRI doesn't change; the additional context is added at query time.
Health: member coverage credential
A member's coverage can change over time: provider migration, gaps in coverage, or coverage with more than one provider. Storing the provider as a fixed value would produce outdated references.
health:coverage/credential:patient-id=12345678
The resolver applies a fallback strategy: it queries the first available provider and if the credential isn't found, tries the next one. The DRI resolves at query time, always reflecting the current state.
Multinational with tenant: supplier by legal entity
A SaaS platform used by a company operating in multiple countries. Each country has its own supplier management system, its own API, and its own tax identifier format.
tenant:acme:ar/supplier:cuit=20123456789
tenant:acme:cl/supplier:rut=76354921-5
tenant:acme:mx/supplier:rfc=XYZ123456789
The left side combines tenant and legal entity by country. The right side respects the local convention without the gateway knowing anything about it. Adding a new subsidiary or tenant means registering an additional resolver, without touching existing references. The context hierarchy grows naturally with the system.
How the gateway works
The resolution flow is simple: the gateway receives the identifier, extracts the context, and delegates to the corresponding resolver.
client → gateway → resolver(commerce:orders) → actual service
- Receives the identifier
- Extracts the context (left side)
- Delegates to the registered resolver for that context
- The resolver fetches the resource and returns the response
The gateway has no knowledge of concrete resources. As an orientative reference, a possible Java implementation:
gateway.register("commerce:orders", new OrderResolver());
gateway.register("finance:accounts", new AccountResolver());
gateway.register("health:coverage", new CoverageResolver());
public interface ResourceResolver {
Response resolve(ResourceIdentifier identifier);
}
Optional preferences
The identifier supports expressing preferences about how the resource should be resolved, with a syntax inspired by HTTP's Accept header. For example, when querying available payment methods, you can indicate a preference for debit over credit:
payments:methods/available:customer:id=109234;debit,q=0.9;credit,q=0.7
The meaning of q is defined by the contract between whoever builds the reference and whoever resolves it. The gateway doesn't need to interpret it. This capability is completely optional.
I implemented this in Java and found it useful in practice. If you try it in your own context or have ideas to improve it, I'd love to read them in the comments.