Gateway

Running Recap’s stateless HTTP/JSON gateway server.

  1. Overview
  2. Usage
  3. Configuration
  4. API
    1. OpanAPI
    2. Swagger
    3. Redoc
  5. Docker

Overview

Recap’s HTTP/JSON server comes with a gateway API that you can use to query systems and schemas. The server doesn’t require any database or storage. It’s simply a gateway that connects to systems and returns Recap schemas.

Usage

Use the recap serve command to start the server.

recap serve

See the CLI documentation for additional serve parameters and examples.

The gateway server is a simple FastAPI application. The serve command starts the FastAPI application using uvicorn. You may choose any ASGI-compatible server. See FastAPI’s documentation for more information.

You can query a system like so:

curl http://localhost:8000/gateway/ls/postgresql://user:pass@localhost:5432/testdb

And read a schema:

curl http://localhost:8000/gateway/schema/postgresql://user:pass@localhost:5432/testdb/public/test_types

Configuration

The gateway will work out of the box without any configuration. Any URL with a compatible client integration will work. However, you can configure Recap to save access credentials in an environment variable using the RECAP_URLS environment variable.

  • RECAP_URLS: A JSON-encoded list of URLs to connect to.

See the configuration for more information on the RECAP_URLS environment variable.

You can also set environment variables in .env files or secrets files. See Recap’s configuration documentation for more information.

API

Recap’s gateway server exposes a very simple HTTP/JSON API with two endpoints:

  • /gateway/ls/[url] - List children of a URL.
  • /gateway/schema/[url] - Get a schema for a URL.

OpanAPI

An OpenAPI schema is available at http://localhost:8000/openapi.json.

Swagger

A Swagger UI is available at http://localhost:8000/docs.

Redoc

A Redoc UI is available at http://localhost:8000/redoc.

Docker

Recap’s gateway server is available as a Docker image at ghcr.io/recap-build/recap:latest.

docker pull ghcr.io/recap-build/recap:latest

You can run the server using the docker run command:

docker run \
    -p 8000:8000 \
    -e "RECAP_URLS='[\"postgresql://user:pass@pg:5432/testdb\"]'" \
    ghcr.io/recap-build/recap:latest

This command binds the server to port 8000 and connects to a PostgreSQL system named pg. See the secrets documentation if you wish to use secrets files instead for your connection strings.