Question

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?

Was it helpful?

Solution

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".

Licensed under: CC-BY-SA with attribution
scroll top