Falling Fruit API

NodeJS API using express and pg-promise.

You can browse the OpenAPI definition for the main branch here, and for the live API here.

Status

Live at https://fallingfruit.org/api/0.3 and powers https://fallingfruit.org (falling-fruit-web).

Development

Installation

• Clone the repo and change into the new directory.

  git clone https://github.com/falling-fruit/falling-fruit-api
  cd falling-fruit-api

• Install the node version specified in the .nvmrc file. This is easiest using nvm.

  nvm install
  nvm use

• yarn is already provided (see .yarn/releases). Use it to install dependencies.

  yarn

• Copy .env.example to .env and update the values as needed.

cp .env.example .env

• Install Docker (with Compose). It is not required to run the API itself, but is used to provision a disposable PostGIS database for the end-to-end tests (yarn test:e2e) and for generating database types (yarn codegen).

• If you want to use the e2e database in the API, set DATABASE_URL to the value in .env.test and run yarn e2edb:up.

• You can also provision your own PostGIS database - see .github/workflows/ci.yml for a setup to recreate.

Usage

yarn start

Visit http://localhost:3300.

Testing

Tests use the built-in node --test runner, split by file naming convention:

• yarn test: run everything (unit and e2e).
• yarn test:unit: run unit tests only (test/**/*.test.ts).
• yarn test:e2e: run e2e tests only (test/**/*.e2e.ts).

e2e tests require a database. yarn test:e2e starts the dockerized PostGIS database (yarn e2edb:up), migrates it, and runs them. Tear it down afterwards with yarn e2edb:down.

Database migrations

Migrations are managed with dbmate and located in ./db/migrations. Create a new migration with:

yarn dbmate new <migration_name>

Add SQL statements in the -- migrate:up and (optional) -- migrate:down sections, then run yarn codegen.

Database types

Row types in src/db/generated/ are derived from the live Postgres schema by kanel (configured in .kanelrc.cjs). Regenerate after any schema change (migration):

yarn codegen

Documentation

The OpenAPI spec is generated from Zod schemas, which are the single source of truth for both runtime validation and the documentation:

• src/schemas/: Zod component schemas, parameters, and security schemes, registered with @asteasolutions/zod-to-openapi.
• src/routes/*.ts: Each route declares its OpenAPI operation inline via a compact spec alongside its handler. The same schemas drive runtime request validation and compile-time response typing: a handler's return type is bound to its documented 2xx response schema.
• docs/base.yml: Static metadata (info, tags, servers).

scripts/build-openapi.ts registers every schema and route operation, merges base.yml, and writes the bundled docs/openapi.yml.

Build and validate the spec:

yarn docs

Type-check the TypeScript sources:

yarn typecheck