I have a RESTful API that I'm designing which uses numeric primary keys for all of its resources. However one type of resource has a convenient natural key, which I'd like to be able to use as an optional way to specify the individual resource. For consistencies sake all resources will be accessible via their primary key.
As it stands, I can do this (assuming 23 is the primary key):
mysite.com/api/v0/sites/23/
However, I'm wondering if there's an idiomatic way to specify an alternate natural key for a resource.
So far I was thinking of doing something like this:
mysite.com/api/v0/sites/?domain-name=someothersite.com/
So an individual site resource would be accessible by both its primary key and a natural key (its domain name). My primary concern is doing this in and idiomatic fashion, seeing as I'd like to make the API as straightforward to use as possible.
In your particular situation, the primary key (integer) can always easily be differentiated from the domain name (string including a period). It seems perfectly valid (and intuitive) to allow both in the same location of the URL:
mysite.com/api/v0/sites/23
mysite.com/api/v0/sites/someothersite.com
Documenting it is straightforward too, as each is a unique identifier for a site:
mysite.com/api/v0/sites/{id}
id: primary key or fully-qualified domain name