Basic Flask API

[ghost]

a basic flask api is working, i am just filling up the database with some data so we have more to query (had to wait with ingesting more data until i was sure the data model works/is convenient for the flask api) which should be done by tonight. once that's done you will be able to issue the following GET requests:

Metadata

• wget http://[IP]:5000/api/v0/gridmeta
• wget http://[IP]:5000/api/v0/gridmeta/datasets/12,8,10

Select

• wget http://[IP]:5000/api/v0/griddata/dataset/6/var/12 (takes quite long, be patient)
• TODO: POST

Spatial Aggregation

• wget http://[IP]:5000/api/v0/griddata/aggregate/spatial/dataset/6/var/12
• TODO: POST

Temporal Aggregation

• wget http://[IP]:5000/api/v0/griddata/aggregate/temporal/dataset6/var/12
• TODO: POST

[njmattes]

http://[IP]:5000/api/v0/griddata/select/1/1

I'd kill the /select/ since the http method should represent the action (create, retrieve, update, delete).

If the variable's id is to be passed in the URL, I'd precede it with a parameter name so the URL remains human readable. Ostensibly we're treating the meta_id as the identifier of the griddata. So something like http://[IP]:5000/api/v0/griddata/1/var/1.

As a general rule, I'd probably use POST for most of these, except the first one where we're retrieving the metadata. Using POST may seem odd since POST suggests that we're creating a new record, and we're not adding anything to the db. But we're creating a new temporary record of sorts in the the user's session. Or in a server-side session, or db cache perhaps. Using POST also allows us to pass all the parameters as a JSON blob. So that the polygon can be passed as a GeoJSON blob perhaps.

Using POST also allows us to eg limit requests form certain web services to sub-selecting data through POST while other services are allowed to retrieve entire datasets through GET.

[njmattes]

For the select endpoint, when you say 'cannot specify only date or only geom', doesn't the first endpoint (wget http://[IP]:5000/api/v0/griddata/select/1/1) only specify date?

For spatial aggregation (http://[IP]:5000/api/v0/griddata/aggregate/spatial/1/1) how are we specifying regions to aggregate to? Admittedly, I haven't looked at extract.py lately. Do we only have one region set ingested right now?

[ghost]

ok, the flask service is running, just adjusted the urls above a little and merged severin into develop.

ok, @njmattes, im incorporating your suggested changes.

to answer your questions:

• the first 1 is the meta_id and the second 1 the var_id. so that URL does neither specify date nor the geom
• i have not ingested regions yet though the ingest_shapes.py script is working and i could ingest regions anytime such as i have done for EEZ regions. if i specify the regions by ID then GADM, EEZ etc. aggregation will work but not aggregation with a directly user-provided polygon. i discussed that last friday with @ricardobarroslourenco and @abrizius and i had the impression after that that aggregation with a directly provided polygon has priority as for now. however, ultimately we want to support both and that is why i was planning to write 2 routes but have yet only written the one for the directly provided polygon. the polygon currently has to be a rectangle with comma-separated coordinates, as you can see in the URL.

[njmattes]

• Oh right, var_id. Derp.
• I'm not sure what went on Friday. But I thought that part of prototype version 0 was to aggregate a gridded dataset to GADM0. Are we moving away from that? Doesn't matter to me either way really, but just curious.

[ghost]

we still want aggregation to GADM but also want aggregation to polygons that are provided directly by the user. it's just that we probably need two separate flask routes for that, one where the polygons are specified by IDs and one where they are provided directly. so far ive just written one of these routes but when it comes to the second route i at least have the ingestion script ingest_shapes.py already ready.

[ghost]

@njmattes are you saying that most routes (except for metadata) should be reachable with a GET as well as POST or only POST, i'd say both? is views.py in the severin branch now according to your suggestions? also added 2 new routes: get_polymeta , get_polydata. what were you planning to do inside get_polydata? in my implementation i just return the geometry of the polygon as a geojson, not some value associated to the polygon (e.g. total crop yield). is that the same you were planning todo with this route?

[njmattes]

The method we're using should really indicate the type of operation we're performing. Typically POST=Create, GET=Retrieve, PUT=Update, DELETE=Delete (or CRUD for short). I'd say use GET for retrieving metadata, and POST for creating 'new', cropped views of the gridded data.

[njmattes]

I hadn't really thought through the get_polydata route. But yes, just returning a GeoJSON representation of the object is probably a good approach. We'll need such a feature is we want to grab the objects we're using as a graphical overlay from the database rather than storing them locally on the web server.

[ghost]

@njmattes ok, just merged severin branch into develop. if you run python run.py flask will be up and running and all the GET's should work, haven't debugged the POST's yet though. im continuing in severin with the ingestion script. updated the urls above.

[njmattes]

Cool. I'll work out the rest of the API features for these routes this week. I'm also going to set up a uWSGI script to launch the web interface for the API. Will make it easier to start and reboot. I'll send you the command(s) once it's done.