PostgREST / postgrest

REST API for any Postgres database
https://postgrest.org
MIT License
23.27k stars 1.02k forks source link

Improve readability of Curl examples with many query parameters #3561

Closed laurenceisla closed 3 months ago

laurenceisla commented 3 months ago

Didn't see a complain about this, but it seems to me that some Curl examples that have many query parameters or are too long, could be better expressed by separating said query parameters from the URL. Mostly for didactic purposes (could be easier to learn/understand).

For instance, the OR across embeddings looks really cluttered:

curl "http://localhost:3000/films?select=title,actors(),directors()&directors.first_name=eq.John&actors.first_name=eq.John&or=(directors.not.is.null,actors.not.is.null)"

Using -G in Curl allows to send -d as query parameters in get requests. The previous request would look like this:

curl -G "http://localhost:3000/films" \
  -d "select=title,actors(),directors()" \
  -d "directors.first_name=eq.John" \
  -d "actors.first_name=eq.John" \
  -d "or=(directors.not.is.null,actors.not.is.null)"

It also allows comments if needed and the complete URL could go at the start as a comment too:

# curl "http://localhost:3000/films?select=title,actors(),directors()&directors.first_name=eq.John&actors.first_name=eq.John&or=(directors.not.is.null,actors.not.is.null)"

curl -G "http://localhost:3000/films" \
  -d "select=title,actors(),directors()" \
  -d "directors.first_name=eq.John" \
  -d "actors.first_name=eq.John" \
  # filter the top level resource using "or"
  -d "or=(directors.not.is.null,actors.not.is.null)"