loicdtx / ministac-api

JSON REST API for ministac catalog

Ministac-api

*JSON REST API for ministac *

Resources

List of resources

Example usage with python

import requests
import datetime as dt
from pprint import pprint

# Get all available collections
r = requests.get('http://127.0.0.1:5000/ministac/api/v0/collections')
pprint(r.json())


# Get metadata of a collection
r = requests.get('http://127.0.0.1:5000/ministac/api/v0/collections/landsat_sr_8')
pprint(r.json())


# Get metadata of an item
r = requests.get('http://127.0.0.1:5000/ministac/api/v0/collections/landsat_sr_8/items/LC08_L1TP_028045_20171121_20171206_01_T1')
pprint(r.json())


# Search items using various filters
params = {'collection': 'landsat_sr_8',
          'maxCloudCover': 12,
          'endDate': dt.datetime(2017, 12, 1).isoformat()}

r = requests.post('http://127.0.0.1:5000/ministac/api/v0/search', json=params)
# Or
r = requests.get('http://127.0.0.1:5000/ministac/api/v0/search', params=params)

pprint(r.json())

Also see example (in spanish) at http://www.loicdutrieux.net/ministac-api/#/.

HTTP status codes

200: OK

400: Bad request

404: Not found

Install

You must first configure ministac (database setup and configuration file), then.

Locally

git clone [email protected]:loicdtx/ministac-api.git
cd ministac-api
pip install -r requirements.txt
pip install -e .
export FLASK_APP=api
flask run

Using docker

git clone https://github.com/loicdtx/ministac-api.git
cd ministac-api
docker build -t ministac-api:latest .
docker run --name ministac-api --rm -d -p 5000:5000 -v ~/.ministac:/root/.ministac ministac-api

Note:

This approach serves uwsgi binary protocol and must be combined with a nginx server.

Using docker-compose

First configure the nginx file, env_file and .ministac files. Then:

# Start the database container
docker-compose up -d db
# Create the ministac tables
docker-compose run --rm --entrypoint "python3" flaskapp -c "from ministac.db import init_db; init_db()"
# Start the cluster
docker-compose up -d

Note:

This approach serves uwsgi binary protocol and must be combined with a nginx server.

ministac-api's Issues

typo

small typo in https://github.com/loicdtx/ministac-api#using-docker

cd ministac-api

instead of

cd ministac-api.git

Paginator for search endpoint

On the model of EarthExplorer JSON API https://earthexplorer.usgs.gov/inventory/documentation/json-api?version=1.4.0#search

maxResults, startingNumber

http or socket ?

check this ones:

https://github.com/CONABIO/antares3-sandbox/tree/master/notebooks/ministac

in particular:

https://github.com/CONABIO/antares3-sandbox/blob/master/notebooks/ministac/ministac_api.ipynb

Maybe you need to change your CMD in your Dockerfile to:

uwsgi --http 0.0.0.0:5000 --master -w api:app

but not sure if you want to use a nginx wserver
:)

Move resource access away from API root

To avoid conflicts with other endpoints, collection resources should be at collections/<collection_name> and items at collections/<collection_name>/items/<item_id> as per OGC specs https://github.com/opengeospatial/ogcapi-features

Suggested by @mbsantiago

add in README next commands for nginx server

It will be useful to have next recommendations in README when using nginx

Conf file for nginx

upstream ministac {

     server <server where ministac-api is deployed>:5000; 

}

server {

...

 location /ministac/ {

        uwsgi_pass <server where ministac-api is deployed>:5000;

        include     ./uwsgi_params; 

    }

    

}

And create uwsgi_params (in the same directory of conf file for nginx):

uwsgi_param  QUERY_STRING       $query_string;
uwsgi_param  REQUEST_METHOD     $request_method;
uwsgi_param  CONTENT_TYPE       $content_type;
uwsgi_param  CONTENT_LENGTH     $content_length;

uwsgi_param  REQUEST_URI        $request_uri;
uwsgi_param  PATH_INFO          $document_uri;
uwsgi_param  DOCUMENT_ROOT      $document_root;
uwsgi_param  SERVER_PROTOCOL    $server_protocol;
uwsgi_param  REQUEST_SCHEME     $scheme;
uwsgi_param  HTTPS              $https if_not_empty;

uwsgi_param  REMOTE_ADDR        $remote_addr;
uwsgi_param  REMOTE_PORT        $remote_port;
uwsgi_param  SERVER_PORT        $server_port;
uwsgi_param SERVER_NAME         $server_name;

Return FeatureCollection from search

Instead a simple array of features

Add GET method for search endpoint

In addition to POST. Although this is a tipical GET use case, with query parameters. POST is still needed for 2 reasons listed here
https://github.com/radiantearth/stac-spec/blob/master/api-spec/examples.md#stac-api

suggested by @mbsantiago

advantages? or not? for `n` number of processes when using `uwsgi`

Check benefits for using:

n=<number of processes>
uwsgi --socket 0.0.0.0:5000 --master -w api:app --processes n

in CMD of Dockerfile

add more volumes for data persistence for db container

I normally map this volumes to the filesystem when deploying a DB:

/etc/postgresql
/var/log/postgresql
/var/lib/postgresql

Maybe ask Omar what he suggest? and add them in https://github.com/loicdtx/ministac-api/blob/master/docker-compose.yml ?