stac-fastapi-mongo

MongoDB backend for the stac-fastapi project built on top of the sfeos core API library.

Technologies

This project is built on the following technologies: STAC, stac-fastapi, SFEOS core, FastAPI, MongoDB, Python

Table of Contents

• Installation
• Development
  • Development Environment Setup
  • Pre-commit
• Running the API
  • Build and Run
  • Creating Collections
  • Collection Pagination
• Testing
• Sample Data
• Authentication
  • Environment Variable Configuration
  • Authentication Configuration
  • Examples
    • Admin-only Authentication
    • Public Endpoints with Admin Authentication
    • Multi-user Authentication
• Read-Only Databases
• Contributing
• Changelog

Installation

To install from PyPI:

pip install stac_fastapi.mongo

Development

Development Environment Setup

To install the classes in your local Python env, run:

pip install -e .[dev]

Pre-commit

Install pre-commit.

Prior to commit, run:

pre-commit run --all-files

Running the API

Build and Run

Build the MongoDB backend:

docker-compose up mongo
docker-compose build app-mongo

Run the MongoDB API on localhost:8084:

docker-compose up app-mongo

Creating Collections

To create a new Collection:

curl -X "POST" "http://localhost:8084/collections" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "id": "my_collection"
}'

Note: this "Collections Transaction" behavior is not part of the STAC API, but may be soon.

Collection Pagination

The collections route handles optional limit and token parameters. The links field that is returned from the /collections route contains a next link with the token that can be used to get the next page of results.

curl -X "GET" "http://localhost:8084/collections?limit=1&token=example_token"

Testing

Run the test suite:

make test

Sample Data

Ingest sample data:

make ingest

Authentication

Environment Variable Configuration

Basic authentication is an optional feature. You can enable it by setting the environment variable STAC_FASTAPI_ROUTE_DEPENDENCIES as a JSON string.

Example:

STAC_FASTAPI_ROUTE_DEPENDENCIES=[{"routes":[{"method":"*","path":"*"}],"dependencies":[{"method":"stac_fastapi.core.models.basic_auth.BasicAuth","kwargs":{"credentials":[{"username":"admin","password":"admin"}]}}]}]

Authentication Configuration

The STAC_FASTAPI_ROUTE_DEPENDENCIES environment variable allows you to configure different levels of authentication for different routes. The configuration is a JSON array of objects, each with two properties:

1. routes: An array of route objects, each with method and path properties
2. dependencies: An array of dependency objects, each with method and kwargs properties

Examples

Admin-only Authentication

This example configures all routes to require admin authentication:

[
    {
        "routes": [
            {
                "method": "*",
                "path": "*"
            }
        ],
        "dependencies": [
            {
                "method": "stac_fastapi.core.models.basic_auth.BasicAuth",
                "kwargs": {
                    "credentials": [
                        {
                            "username": "admin",
                            "password": "admin"
                        }
                    ]
                }
            }
        ]
    }
]

Public Endpoints with Admin Authentication

This example makes specific endpoints public while requiring admin authentication for all others:

[
    {
        "routes": [
            {
                "method": "*",
                "path": "*"
            }
        ],
        "dependencies": [
            {
                "method": "stac_fastapi.core.models.basic_auth.BasicAuth",
                "kwargs": {
                    "credentials": [
                        {
                            "username": "admin",
                            "password": "admin"
                        }
                    ]
                }
            }
        ]
    },
    {
        "routes": [
            {"path": "/", "method": ["GET"]},
            {"path": "/conformance", "method": ["GET"]},
            {"path": "/collections/{collection_id}/items/{item_id}", "method": ["GET"]},
            {"path": "/search", "method": ["GET", "POST"]},
            {"path": "/collections", "method": ["GET"]},
            {"path": "/collections/{collection_id}", "method": ["GET"]},
            {"path": "/collections/{collection_id}/items", "method": ["GET"]},
            {"path": "/queryables", "method": ["GET"]},
            {"path": "/queryables/collections/{collection_id}/queryables", "method": ["GET"]},
            {"path": "/_mgmt/ping", "method": ["GET"]}
        ],
        "dependencies": []
    }
]

Multi-user Authentication

This example configures admin authentication for all routes, with a separate reader user that can access specific read-only endpoints:

[
    {
        "routes": [
            {
                "method": "*",
                "path": "*"
            }
        ],
        "dependencies": [
            {
                "method": "stac_fastapi.core.models.basic_auth.BasicAuth",
                "kwargs": {
                    "credentials": [
                        {
                            "username": "admin",
                            "password": "admin"
                        }
                    ]
                }
            }
        ]
    },
    {
        "routes": [
            {"path": "/", "method": ["GET"]},
            {"path": "/conformance", "method": ["GET"]},
            {"path": "/collections/{collection_id}/items/{item_id}", "method": ["GET"]},
            {"path": "/search", "method": ["GET", "POST"]},
            {"path": "/collections", "method": ["GET"]},
            {"path": "/collections/{collection_id}", "method": ["GET"]},
            {"path": "/collections/{collection_id}/items", "method": ["GET"]},
            {"path": "/queryables", "method": ["GET"]},
            {"path": "/queryables/collections/{collection_id}/queryables", "method": ["GET"]},
            {"path": "/_mgmt/ping", "method": ["GET"]}
        ],
        "dependencies": [
            {
                "method": "stac_fastapi.core.models.basic_auth.BasicAuth",
                "kwargs": {
                    "credentials": [
                        {
                            "username": "reader",
                            "password": "reader"
                        }
                    ]
                }
            }
        ]
    }
]

Note for Read-Only Databases

If you are using a read-only MongoDB user, the MONGO_CREATE_INDEXES environment variable should be set to "false" (as a string and not a boolean) to avoid creating indexes in the database. When this environment variable is not set, the default is to create indexes. See GitHub issue #28

Contributing

Contributions are welcome! Here's how you can help:

How to Contribute

1. Fork the repository - Create your own fork of the project
2. Create a feature branch - git checkout -b feature/your-feature-name
3. Commit your changes - Make sure to write clear, concise commit messages
4. Push to your branch - git push origin feature/your-feature-name
5. Open a Pull Request - Describe your changes in detail

Development Guidelines

• Follow the existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Make sure all tests pass before submitting a PR

Reporting Issues

If you find a bug or have a feature request, please open an issue on the GitHub repository.

Changelog

For changes, see the Changelog