HTTP GET vs GET+POST for /search, /place, /reverse place endpoints

The Question at Hand

For API 1.0.0, should our core endpoints, /search, /reverse, and /place offer HTTP POST requests, or only accept GET requests at this time?

Summary of points

Exclusively GET

When we launch 1.0.0 of the API, we won't be supporting batch geocoding, and so for /search/ and /reverse, API users will be requesting information for a single place per call. As this is just requesting information about a record (or records) and not affecting the records themselves, they fall along the lines of what should be considered a classic HTTP GET request.

While URLs may get somewhat long, the syntax will be clear and straightforward for structuring one of these calls. We are not likely to exceed the ~2000c suggestion for a URI.

Also, keeping in line with comparable geocoders and search services, most only offer GET requests for these functions.

Meanwhile for /place, a user may request the records more than one single location, but even then, we can compact the results into a single JSON FeatureCollection with each place its own feature.

GET + POST

The arguments for why to support GET are sound (👍 me), but we also are creating a pretty complex query structure that may get overwhelming for many types of queries. There's a lot you can do in this system, for instance, the passing of geometries, which are done through verbose statements of geometries and parameters. It would be a lot nicer to just pass these in as JSON objects.

We'll have to write a schema for accepting these queries as JSON no matter what for batch geocoding, why not get a head start now?

Start by reviewing the /search, /reverse, and /place endpoint requirements and the GET-versus-POST arguments in this issue. Compare the implications for single requests, complex geometry queries, and future batch geocoding; done means reaching and recording an API 1.0.0 request-method decision.