Open Catalog API

API documentation

Open Catalog API is a RESTful API for public software catalogs. It powers national open source catalogs for public administrations:

• 🇮🇹 developers.italia.it
• 🇨🇭 swiss/oss-catalog

Requirements

• Golang 1.27+
• PostgreSQL

Development

To start developing:

1. Clone the repo

2. Build and start the containers

   docker compose up

Docker Compose will bring up the app and PostgreSQL containers.

Wait until the Docker logs explicitly say the API is up and you can use its endpoints at http://localhost:3000/v1/.

Configuration

You can configure the API with environment variables:

• DATABASE_DSN: the URI used to connect to the database, fe postgres://user:password@host:5432/dbname. Supports PostgreSQL and SQLite.

• PASETO_KEY (optional): Base64 encoded 32 bytes key used to check the PASETO authentication tokens. You can generate a key and a token with the built-in subcommand:

  open-catalog-api token create

  Pass --key to use an existing key, --sub to identify the caller, and --expiry to set a custom duration (default: 1 year, 0 = never expires).

  If not set, the API will run in read only mode.

• ENVIRONMENT (optional): test turns the rate limiter and the event purge off, for the test suite. Any other value is a normal run. Default production.

• MAX_REQUESTS (optional): number of requests per minute after which responses will be ratelimited. Default: no limit.

• TRUSTED_PROXIES (optional): comma separated list of addresses or CIDRs of the reverse proxies in front of the API, fe 10.0.0.0/8,192.168.1.7. The X-Forwarded-For header is trusted only on requests coming from these addresses, and its first entry is the client the rate limit counts. Leave it empty when the API is exposed directly: the header is then ignored and the client is the peer of the connection. Default: empty.

• WEBHOOK_DEBOUNCE_MS (optional): delay in milliseconds before a webhook is dispatched after the last write on the same resource and event. Set to 0 to disable debouncing entirely. Debouncing is per replica. Default: 1000.

• WEBHOOK_DEBOUNCE_MAX_MS (optional): hard cap in milliseconds on how long a delivery can be deferred by repeated writes on the same resource and event. Set to 0 to disable the cap. Ignored when WEBHOOK_DEBOUNCE_MS is 0. Default: 10000.

• EVENT_RETENTION_DAYS (optional): how many days the audit trail is kept. Every create, update and delete of a catalog entity is an event recording the entity, the kind of change, who made it and when, readable at GET /v1/events. Older events are deleted at startup and once a day. Set to 0 to keep them forever. Default: 365.

Contributing

This project exists also thanks to your contributions! Here is a list of people who already contributed to this repository:

License

The source code is released under the AGPL version 3.

The version control system provides attribution for specific lines of code.