0

I'm in the starting phases of designing an API. I'd like it to be Restful and comply with what's commonly considered best practices.

One of my resources need to accept several query string parameters. Here's an example:

{
  "pick_up": {
    "datetime": "20200301T1400",
    "location": {
      "lat": 40.68231,
      "lng": -73.52935
    }
  },
  "drop_off": {
    "datetime": "20200401T1400",
    "location": {
      "lat": 40.68231,
      "lng": -73.52935
    }
  }
}

The above is how I would probably represent the parameters as a JSON. That could be converted to a query string:

pick_up%5Bdatetime%5D=20200301T1400&pick_up%5Blocation%5D%5Blat%5D=40.68231&pick_up%5Blocation%5D%5Blng%5D=-73.52935&drop_off%5Bdatetime%5D=20200401T1400&drop_off%5Blocation%5D%5Blat%5D=40.68231&drop_off%5Blocation%5D%5Blng%5D=-73.52935

That will work, but it'll look ugly. Maybe something like this would look prettier:

pick_up_datetime=20200301T1400&pick_up_location_lat=40.68231&pick_up_location_lng=-73.52935 ....

Aside from the subjective "pretty"factor, are there any benefits of one over the other? Perhaps in terms of generally accepted best practice, security, RESTful design, etc?

  • Regarding the naming of query params I'd prefer simple names over nested ones, but that's just opinionated. However, in your query example, you're apparently fully specifying an exact match, which smells a bit. This should normally be done using the URI of the item in question. Queries of this resource should probably specify time and location ranges. – Hans-Martin Mosner Feb 2 at 10:07
  • @Hans-MartinMosner not to mention many people might store lat and long as floats. Equality checks on that? – Jan Dorniak Feb 2 at 10:13
  • just post the json – Ewan Feb 2 at 10:23
  • @Ewan use POST instead of GET? Is that restful??? – ProgrammerNewbie Feb 2 at 14:03
  • do you want it RESTfull or good – Ewan Feb 2 at 14:11
3

Aside from the subjective "pretty"factor, are there any benefits of one over the other? Perhaps in terms of generally accepted best practice, security, RESTful design, etc?

There isn't much difference between the two approaches

REST doesn't care what spellings you use for resource identifiers; general purpose components don't try to extract any semantic information from the URI. So the server can encode any information it likes into the URI at its own discretion.

application/x-www-form-urlencoded key value pairs can be a convenient choice because web browsers have forms; the processing rules associated with the GET method describe how the data in the input controls should be copied into the query part. That means you can describe a URI template in HTML, and it will all "just work".

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.