search

opensanctions / yente

API for OpenSanctions with support for entity search and bulk matching of data collections. Supports Reconciliation API spec.
https://www.opensanctions.org/docs/yente/
MIT License
71 stars 29 forks source link

Array query params handling #380

Open kryvel opened 10 months ago

kryvel commented 10 months ago

Hello,

I would like to discuss the handling of GET query parameters in the OpenSanctions API.

After a thorough debugging, I have identified the reason why my query is not functioning as expected. It is a simple matching request with excluded datasets, as shown below:

Original Query:

https://api.opensanctions.org/match/sanctions?exclude_dataset[]=ua_nabc_sanctions&exclude_dataset[]=ua_nsdc_sanctions&exclude_dataset[]=ua_sfms_blacklist

However, the API expects the following syntax for array parameters:

Expected Query Syntax:

?exclude_dataset=ua_nabc_sanctions&exclude_dataset=ua_nsdc_sanctions&exclude_dataset=ua_sfms_blacklist

In my opinion, this approach seems a bit unconventional. Typically, arrays in GET queries are passed in one of the following common ways:

  1. Using square brackets for each parameter value:

    param[]=value1&param[]=value2...

  2. Comma-separated values for a single parameter:

    param=value1,value2...

Is this behavior the intended and expected behavior for the OpenSanctions API?

Thank you for your clarification.

pudo commented 10 months ago

Hey! I think there may be a weird programming language idiosyncrasy here: Python likes the straight variant, whereas PHP and Ruby seem to parse the square bracket syntax more easily. Since I'm not super keen on breaking the API, perhaps we could look into defining x[] as an alias for the x variant?

kryvel commented 10 months ago

Hi, Friedrich I believe an alias would be more than enough in this case. However, it would be great to mention such behaviours in the documentation within the parameter description, so users won't be confused by the query syntax.