RESTful API behavior for entitys with two independent primary keys

Question

I have the following entity:

<car>
    <carID>7</carID>
    <...>...</...>
    <externalCarID>23890212</externalCarID>
</car>

The problem is now that carID and externalCarID are both independent primary keys that are used by/for different systems and it should be possible for API clients to access a car entity with both the carID xor the externalCarID.

Both keys are ints and they do not use disjoint sets:

carID(7) != externalCarID(7)

I have thought of the following solutions:

1. Access it with /restapi/car/7 and /restapi/externalcar/23890212
2. Use parameters e.g. like /restapi/car/7?type=regular and /restapi/car/23890212?type=ext
3. Send the information somewhere in the header - but where?

Some tips how to handle this or feedback on my solutions, preferably with the reference to REST / HTTP specs, would be great!

Background about the primary keys:

Lets say our invoice systems needs the carID and our parent company controlling system needs the externalCarID. I do not like that at all, but its a running system and there is no way for me to change it right now.

Scientistic

Answer 1

I'd recommend that you pick one ID as the 'real primary', and access it as suggested:

/restapi/car/7

If you control one of the IDs, then I'd suggest using that as the 'real primary'.

The other ID, even though it's a unique identifier should probably be accessed using a query parameter:

/restapi/car?extid=23384

There are some similar questions which may help:

REST API DESIGN - Getting a resource through REST with different parameters but same url pattern

Different RESTful representations of the same resource

One final thing to consider is redirecting your url for 'extid' to the canonical URL for that resource.

Lantha

The trouble is a query parameter is usually considered as a filter. So /restapi/car/7 will return a single item with a 200/404 response depending on whether the key exists. However, /restapi/car?extid=23384 will always return a 200 response with a collection. In this case, as the query parameter is a unique key, the collection will contain a single item, or empty if no matching record exists. – Confidante

Answer 2

Of the three options presented, first one looks best to me. Especially considering each external system will use only one of base urls. For the second option, you may as well use /restapi/car/?extid=23384 which looks cleaner. In the third case, in my opinion headers are rather for metadata, so using them not for managing presentation context but to completely change object returned by url is not a clean option. Personally, depending of your performance requirements, I would either go for the first solution or a regular /rastapi/car/7 for id I'd consider primary one in my system and restapi/car/?extid=1234 for secondary unique key, probably redirecting GET to canonical url, if it wouldn't hit performance too much.

Aphaeresis