Resources and Their Identifiers: URI, URL and URN

A resource is anything an API lets a client name and act on: an order, a customer, the list of an order's items, even a search. Its identifier is a URI, a uniform resource identifier. A URL is a URI that also says how to reach the resource, such as https://api.example.com/orders/42; a URN is a URI that names something permanently without saying where it is, such as a book's ISBN.

Every URI starts with a scheme, the part before the colon. https: says to fetch over HTTP with TLS; urn: says what follows is a name in a registered namespace, here isbn. That is how a program knows what kind of identifier it has.

A URN cannot be fetched. urn:isbn:0451450523 identifies one edition of a book for ever, wherever copies of it are, but no client can send a request to it. A URL can be fetched, but may stop working when the server moves.

In practice, an API's URIs are URLs. Specifications and libraries say URI because it is the general term; documentation says URL because that is what a developer pastes into a browser. Both are right for an API path. The difference matters when a field holds an identifier that is not a location, such as a namespace in a schema, which is a URI that need not resolve to anything.

A resource is not a database table. A resource is whatever the client needs to name. One table can back several resources, such as open orders and archived orders, and one resource can draw on several tables.

So name every resource with a URI, and remember that the URI identifies the resource; the server decides what representation it returns.