1

I need to design an API endpoint that accepts a list of composite identifiers for a GET request

Lets say an identifier is the composite of these 2 attributes:

  • type - int - can have multiple ids associated
  • id - int - can belong to multiple types

and lets say a client wants to query for the following items:

  • type 10, id 99
  • type 10, id 98
  • type 11, id 89
  • type 12, id 79

What would be a standard way to design this

Some options I've been contemplating

  1. Single query string parameter, with type:id expected in an explicit order

    • /endpoint?typeid=10:99&typeid=10:98&typeid=11:89&typeid=12:79

  2. Single query string parameter, with explicitly called out args for each part of the composite

    • /endpoint?q=type:10+id:99&q=type:10+id:98&q=type:11+id:89&q=type:12+id:79

  3. Same as 2, but comma separated

    • /endpoint?q=type:10+id:99,type:10+id:98,type:11+id:89,type:12+id:79
Improve this question

1 Answer 1

Reset to default
1

Using query parameters is a "standard" way for requesting a server-side filtering on entities.

The parameters format is really up to you so, basically, none of your options is wrong. As REST is about uniform interface you can infer that simplicity and non-ambiguity is something desirable. Therefore, you should prefer what is more plain and simple.

Among your options I would go with the number 1, but it's a personal preference based on the parameter name (it carries more "semantics").

As you certainly know, query params aren't always great when you need to perform really complex filtering. Another approch would be to design a "filterRequest" resource and interact with it using a POST.

The sense of the operation would be:

  1. I submit a filtering request to the server (say, I open a ticket: "please give me those resources matching my criteria")
  2. The server processes the request and returns me the list I want

Maybe this choice could be worthwhile if you plan to add more filtering options (so it enhances expandability and reuse). Conversely, you'll find yourself struggling against a query that tends to become unreadable.

Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.