Endpoint Design Question - Filtering

problem.txt

PROBLEM: 

I need to filter on a list of IO's based on active state. Given that this will be passed in from a querystring param,
how should I design the endpoint?

1. Solution 1 - Single Boolean
GET /v2/ios/?active=true -> Returns all the ACTIVE IO's
GET /v2/ios/?active=false -> Returns all the INACTIVE IO's
GET /v2/ios/ -> Returns both ACTIVE and INACTIVE IO's

2. Solution 2 - Double Boolean
GET /v2/ios/?active=true -> Returns all the ACTIVE IO's
GET /v2/ios/?inactive=true -> Returns all the INACTIVE IO's
GET /v2/ios/ -> Returns Both ACTIVE and INACTIVE IO's


3. Solution 3 - String
GET /v2/ios/?type=active -> Returns all the ACTIVE IO's
GET /v2/ios/?type=inactive -> Returns all the INACTIVE IO's
GET /v2/ios/?type=both -> Returns Both ACTIVE and INACTIVE IO's
GET /v2/ios/ -> Returns Both ACTIVE and INACTIVE IO's

Use Solution 1, assuming that it's reasonable to return both types of IO's in your default state. (Else, just choose & document a default for the API.) Main reasoning: it's the simplest / clearest.

• it's more explicit about what is being returned
• it's less confusing if there are two flags being set (what if someone manages to send active=true&inactive=true ?)
• a string tied to a generic type will just have to get mapped to explicit meaning anyway

BTW for solution 2, the =true part can probably be removed. So you can just use /v2/ios/?active and /v2/ios/?inactive.

good point @qiao-meng-zefr!

In this case, I definitely like #1 because it maps to how the data is actually represented when it comes back from the API

agreed, solution 1 is the best way to go