Friday, October 20, 2017

Identifiers are for look-up. Names are for search.

We know from the principles of the world-wide web that every URL identifies a specific entity. It's fairly apparent that "https://ebank.com/accounts/a49a9762-3790-4b4f-adbf-4577a35b1df7" is the URL of a specific bank account. Whenever I use this URL, now or in the future, it will always refer to the same bank account. You might be tempted to think that 'https://library.com/shelves/american-literature/books/moby-dick' is the URL of a specific book. If you think renaming and relocating books could never make sense in a library API, even hypothetically, then you can perhaps defend that point of view, but otherwise you have to think of this URL differently. When I use this URL today, it refers to a specific, dog-eared copy of Moby Dick that is currently on the American Literature shelf. Tomorrow, if the book or shelf is moved or renamed, it may refer to a shiny new copy that replaced the old one, or to no book at all. This shows that the second URL isn’t the URL of a specific book — it must be the URL of something else. You should think of it as the URL of a search result. Specifically, the result of this search:

find the book that is [currently] named "moby-dick", and is [currently] on the shelf that is [currently] named "american-literature"

Here’s another URL for the same search result, where the difference is entirely one of URL style, not meaning:

https://library.com/search?kind=book&name=moby-dick&shelf=(name=american-literature)

Understanding that URLs based on hierarchical names are actually the URLs of search results rather than the URLs of the entities in those search results is a key idea that helps explain the difference between naming and identity.

Martin Nally, in API design: Choosing between names and identifiers in URLs.

No comments

Post a Comment