IRI as parameter for filtering ressources

Question

We use IRI for identifying ressource in our API. When we want to filter another ressource with a ressource we have to use the ID part of the IRI. Is that normal?

Exemple :

GET /api/authors
[{
  @id: "/api/authors/45gfd654d",
  name: "John Doe",
}]

GET /api/books?authors=[45gfd654d]

It seems complicated to use because we have to split the IRI to be able to use the last part in others API calls. My question is : What are the guidelines in such case? The ressource must have an id (with only the last IRI part) or to we allow to filter with IRI?

Thank

Answer 1

Indeed a pain! We opted to try and actually use (relative) uris in query parameters.

In many cases we'll also create specialized endpoints like /api/authors/[id]/books. Although ultimately similar, our clients don't ever construct or deconstruct urls. Urls are discovered, so a client will find a 'list of books' link on the author resource.