RFC: Search API Design

[vforgione]

As we begin to plan the API portion of the application, I feel like it's important to get as much feedback from as many people as possible so that we have an exceptionally well tuned API.

I'm splitting off the discussion about how to implement the search API because I believe that this will be different enough from how we design the entity API that it merits its own discussion.

The entities returned from the search API will follow whatever decision we make in the entity API discussion.

To me, having massive query strings is both ugly and an antipattern when building an API. In the context of the search API, we are only interested in one endpoint that performs one action. The simple answer is that we have a well documented specification that lists options and examples for how to search, and all requests are posted to the endpoint with the filtering options embedded as a JSON body:

POST /search

{
  "bounding_box": [
    [1.2345, 2.3456],
    [-1.23345, 2.3456],
    [-1.23345, -2.3456],
    [1.23345, -2.3456],
    [1.23345, 2.3456],
  ],
  "time_span": {
    "start": "2017-01-01T00:00:00+00:00",
    "stop": "2018-01-01T00:00:00+00:00"
  }
}

This can obviously be improved and changed -- we might want to use GeoJSON instead of a literal encoded list of coordinates, or we could implement other filtering factors like fuzzy matching names or fields.

This is totally open.

[levyj]

Maybe this is too infrequent a use case to worry about but GET calls are easier from a browser. It is not unheard of that I send someone a link to a fully created API call (ugly though it may be) on the Chicago Data Portal and basically say, "Click this."

That is not necessarily to disagree with the POST approach, just to offer a perspective into the mix.

[vforgione]

We're separating our Web UI from the API pretty drastically. Under the hood they're going to use the same set of action logic to perform the lookup.

The Web will most likely uses a form and post the data to the server; so the parallel via the API is a post as well I guess.

It's not a bad consideration -- definitely something worth keeping in mind.

[vforgione]

Docs for the API are at https://github.com/UrbanCCD-UChicago/plenario2/wiki/API-Documentation .