What's the optimal way to handle multiple parameter inputs in a REST API?

Other Questions API
1

Hey folks, I’m working on a new REST API and I’m stuck on how to deal with multiple parameter inputs. Right now, we’re only using JSON for output, but I’m not sure about the best way to handle input.

For example, we’ve been doing stuff like this:

http://api.example.com/items?id=["12345","67890"]

But I’m wondering if it would be better to do it like this:

http://api.example.com/items?id=12345,67890

What do you think? Is one way better than the other? Should we allow both?

Also, what about more complex filters? Like if we want to filter by type and color:

http://api.example.com/search?q=shoes&filters={"type":["sneakers","boots"],"color":["blue","green"]}

Is this too complicated? Would it be better to split it up?

I know some of our JavaScript devs might prefer JSON inputs, but I’m not sure if that’s the best choice for everyone. Any thoughts or suggestions would be super helpful. Thanks!

2

I’ve dealt with similar issues in my API projects, and I can share what worked well for us. We found that using query parameters for simple filters and POST requests with JSON bodies for more complex queries gave us the best balance of simplicity and flexibility.

For your example with multiple IDs, we opted for comma-separated values:

http://api.example.com/items?id=12345,67890

This approach is clean, widely supported, and easy to parse on the server side.

For more complex filters, we moved away from trying to cram everything into the URL. Instead, we used POST requests with a JSON body for search operations. This allowed us to handle arbitrarily complex filter structures without worrying about URL encoding issues or length limitations.

One thing to keep in mind is consistency. Whatever approach you choose, stick with it across your API. This makes it much easier for developers to work with your endpoints. Also, don’t forget to document your choices clearly in your API documentation!

3

From my experience, the most efficient approach for handling multiple parameter inputs in a REST API is to use query string parameters for simple cases and POST requests with JSON payloads for complex scenarios.

For multiple IDs, I prefer the comma-separated format:

http://api.example.com/items?id=12345,67890

It’s clean, easy to parse, and widely supported across different platforms.

For complex filters, I’d recommend using POST requests with a JSON body. This allows for more structured and flexible querying without URL limitations. You could design an endpoint like:

POST /api/search
{
“q”: “shoes”,
“filters”: {
“type”: [“sneakers”, “boots”],
“color”: [“blue”, “green”]
}
}

This approach provides a clear separation between simple and complex queries, improving overall API usability and maintainability.

4

yo, i’ve seen this kinda thing before. for simple stuff like multiple IDs, go with the comma-separated approach:

http://api.example.com/items?id=12345,67890

it’s clean and easy to work with. but for those complex filters, don’t mess with the URL. use POST requests with JSON bodies instead. keeps things neat and avoids url headaches. just make sure u document it well for the devs!