Standard for API JSON reponses

[njmattes]

{
  "response": {
    "datetime": "2016-03-15 12:00:00-06",
    "status": "OK",
    "status_code": 200,
    "metadata": {
      "timesteps": [
        "2005-12-25 00:00:00-06", "2006-12-25 00:00:00-06"
      ],
      "units": "TKTK",
      "format": "grid"
    },
    "data": [{
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [14.7512, 63.2590] },
      "properties": {
        "values": [6.36, 4.32]
      }
    }]
  },
  "request": {
    "datetime": "2016-03-15 12:00:00-06",
    "url": "/api/v0/",
    "accuracy": 2,
    "geo_accuracy": 4, 
  }
}

[njmattes]

@legendOfZelda I think the first post in this thread is about the minimum for a response. I'm leaving the JSON blob in ints own post so we can edit it as we need revisions.

The response.data key should contain an array of GeoJSON objects. Note that the values in response.data[i].properties.values have been rounded. This is so that the size of the response is manageable. The amount of rounding or significant digits should perhaps be specified in the request.

For mean, min, max, histograms, etc, this can either be done on the client-side with JavaScript using (I believe) the data in this blob. Or on the server, and sent as part of response.data[i].properties. Amount of bins for histograms should probably be sent in the request in that case. The argument against doing this on the server is that it will increase the size of the response. Arguments for it?

[ghost]

so the question is whether we should allow individual users to choose the accuracy of lat, long, value, min, max, etc. + number of bins for histogram VS having their accuracy + number of bins hardcodedly configured on the server, thus the same for all users?

[njmattes]

It wouldn't have to be chosen by the user—it can be hard-coded into the request by the application. At some point, perhaps EDE becomes the backend for a service other than ATLAS that isn't web-based, and prefers higher accuracy. Putting it in the request (or response for that matter) merely allows one to track the presentation of the data. If it's not in the blob at all, it's unclear whether the underlying data is actually eg 6.43 or something more precise.

[ghost]

yes. how about we allow for an accuracy parameter (number of decimals) in the JSON request that is uniform, i.e. for lat, long, values, or one for lat,long and one for values and then we can use st_x, st_y, ROUND within postgis to round according to the number of decimals in the request...(we could of course round within the python code instead of within the db, but doing it within the db already saves a little bandwidth when reading from the db). i added the proposed changes to the above JSON.

[njmattes]

Moved accuracy parameters to the request. We don't want them in response.data[i] because we want to avoid duplicating any redundant information in each pixel from the raster.

[ghost]

oops, yep, absolutely

[njmattes]

Incidentally, as far as development timeline considerations go, the request portion of this blob can be ignored for the time being. Eventually we'll want to return that info with the response so we can verify the responses. But the ATLAS GUI doesn't absolutely need it.

[ghost]

ok. btw, i'm going to write a little python code to extract from postgis and construct geojsons according to the above spec. the queries i'm using are #23. i won't be able to fully dedicate my time to it until saturday though, where i want to finish that though. i will let you know then the latest.

[njmattes]

Looping in @ricardobarroslourenco. This basic format can also be used for results from aggregation as well. It's probably obvious, but changing response.data[i].geometry.type to Polygon or MultiPolygon and modifying the coordinates as necessary—and changing response.metadata.format to poly.

[ricardobarroslourenco]

For me this JSON, with a nested GeoJSON seems to be fine. About the changes in terms of the geometry type of what it is being contained in the GeoJSON, I think that it won't impact much. Perhaps using a python library would help keeping the standard, but actually it is trying to keep the multiple formats presented on its current specification.

[ghost]

The specification is written up on apiary.io