Adding API Endpoints - World Monitor

All JSON API endpoints in World Monitor must use sebuf. Do not create standalone api/*.js or api/*.ts files for new data APIs — the legacy pattern is deprecated and being removed. This guide walks through adding a new RPC to an existing service and adding an entirely new service.

Enforcement: npm run lint:api-contract runs in CI (see .github/workflows/lint-code.yml). It walks every file under api/, pairs each sebuf gateway (api/<domain>/v<N>/[rpc].ts) with a generated service under src/generated/server/worldmonitor/, and rejects any file that is neither a gateway nor listed in api/api-route-exceptions.json. The manifest is the only escape hatch for endpoints that genuinely cannot be proto — OAuth callbacks, binary responses, upstream proxies, operator plumbing — and every entry is pinned to @SebastienMelki via .github/CODEOWNERS. Expect reviewer pushback on new entries. Generation freshness: After modifying any .proto file, run make generate before pushing. The generated TypeScript in src/generated/ is checked in and must stay in sync; .github/workflows/proto-check.yml fails the PR if it drifts.

Prerequisites

You need Go 1.21+ and Node.js 18+ installed. Everything else is installed automatically:

make install    # one-time: installs buf, sebuf plugins, npm deps, proto deps

This installs:

buf — proto linting, dependency management, and code generation orchestrator
protoc-gen-ts-client — generates TypeScript client classes (from sebuf)
protoc-gen-ts-server — generates TypeScript server handler interfaces (from sebuf)
protoc-gen-openapiv3 — generates OpenAPI v3 specs (from sebuf)
npm dependencies — all Node.js packages

Run code generation from the repo root:

make generate   # regenerate all TypeScript + OpenAPI from protos

This produces three outputs per service:

src/generated/client/{domain}/v1/service_client.ts — typed fetch client for the frontend
src/generated/server/{domain}/v1/service_server.ts — handler interface + route factory for the backend
docs/api/{Domain}Service.openapi.yaml + .json — OpenAPI v3 documentation

Adding an RPC to an existing service

Example: adding GetEarthquakeDetails to SeismologyService.

1. Define the request/response messages

Create proto/worldmonitor/seismology/v1/get_earthquake_details.proto:

syntax = "proto3";
package worldmonitor.seismology.v1;

import "buf/validate/validate.proto";
import "worldmonitor/seismology/v1/earthquake.proto";

// GetEarthquakeDetailsRequest specifies which earthquake to retrieve.
message GetEarthquakeDetailsRequest {
  // USGS event identifier (e.g., "us7000abcd").
  string earthquake_id = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string.min_len = 1,
    (buf.validate.field).string.max_len = 100
  ];
}

// GetEarthquakeDetailsResponse contains the full earthquake record.
message GetEarthquakeDetailsResponse {
  // The earthquake matching the requested ID.
  Earthquake earthquake = 1;
}

2. Add the RPC to the service definition

Edit proto/worldmonitor/seismology/v1/service.proto:

import "worldmonitor/seismology/v1/get_earthquake_details.proto";

service SeismologyService {
  // ... existing RPCs ...

  // GetEarthquakeDetails retrieves a single earthquake by its USGS event ID.
  rpc GetEarthquakeDetails(GetEarthquakeDetailsRequest) returns (GetEarthquakeDetailsResponse) {
    option (sebuf.http.config) = {path: "/get-earthquake-details"};
  }
}

3. Lint and generate

make check   # lint + generate in one step

At this point, npx tsc --noEmit will fail because the handler doesn’t implement the new method yet. This is by design — the compiler enforces the contract.

4. Implement the handler

Create server/worldmonitor/seismology/v1/get-earthquake-details.ts:

import type {
  SeismologyServiceHandler,
  ServerContext,
  GetEarthquakeDetailsRequest,
  GetEarthquakeDetailsResponse,
} from '../../../../src/generated/server/worldmonitor/seismology/v1/service_server';

export const getEarthquakeDetails: SeismologyServiceHandler['getEarthquakeDetails'] = async (
  _ctx: ServerContext,
  req: GetEarthquakeDetailsRequest,
): Promise<GetEarthquakeDetailsResponse> => {
  const response = await fetch(
    `https://earthquake.usgs.gov/earthquakes/feed/v1.0/detail/${req.earthquakeId}.geojson`,
  );
  if (!response.ok) {
    throw new Error(`USGS API error: ${response.status}`);
  }
  const f: any = await response.json();
  return {
    earthquake: {
      id: f.id,
      place: f.properties.place || '',
      magnitude: f.properties.mag ?? 0,
      depthKm: f.geometry.coordinates[2] ?? 0,
      location: {
        latitude: f.geometry.coordinates[1],
        longitude: f.geometry.coordinates[0],
      },
      occurredAt: f.properties.time,
      sourceUrl: f.properties.url || '',
    },
  };
};

5. Wire it into the handler re-export

Edit server/worldmonitor/seismology/v1/handler.ts:

import type { SeismologyServiceHandler } from '../../../../src/generated/server/worldmonitor/seismology/v1/service_server';

import { listEarthquakes } from './list-earthquakes';
import { getEarthquakeDetails } from './get-earthquake-details';

export const seismologyHandler: SeismologyServiceHandler = {
  listEarthquakes,
  getEarthquakeDetails,
};

6. Verify

npx tsc --noEmit   # should pass with zero errors

The route is already live. createSeismologyServiceRoutes() picks up the new RPC automatically — no changes needed to api/[[...path]].ts or vite.config.ts.

7. Check the generated docs

Open docs/api/SeismologyService.openapi.yaml — the new endpoint should appear with all validation constraints from your proto annotations.

Adding a new service

Example: adding a hypothetical WeatherService. (No weather domain exists in this repo — the example below is purely illustrative; copy-pasting any path from this section will hit a 404.)

1. Create the proto directory

proto/worldmonitor/weather/v1/

2. Define entity messages

Create proto/worldmonitor/weather/v1/weather_station.proto:

syntax = "proto3";
package worldmonitor.weather.v1;

import "buf/validate/validate.proto";
import "sebuf/http/annotations.proto";

// WeatherStation represents a single ground-based observation station.
message WeatherStation {
  // Unique identifier (e.g., WMO station number).
  string id = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string.min_len = 1
  ];
  // Human-readable station name.
  string name = 2;
  // Operating network (e.g., "NWS", "WMO", "NOAA").
  string network = 3;
  // ISO 3166-1 alpha-2 country code where the station is located.
  string country_code = 4;
  // Date the station first reported observations, as Unix epoch milliseconds.
  int64 first_seen_at = 5 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];
}

3. Define request/response messages

Create proto/worldmonitor/weather/v1/list_weather_stations.proto:

syntax = "proto3";
package worldmonitor.weather.v1;

import "buf/validate/validate.proto";
import "worldmonitor/core/v1/pagination.proto";
import "worldmonitor/weather/v1/weather_station.proto";

// ListWeatherStationsRequest specifies filters for weather station data.
message ListWeatherStationsRequest {
  // Filter by operating network (e.g., "NWS"). Empty returns all.
  string network = 1;
  // Filter by country code.
  string country_code = 2 [(buf.validate.field).string.max_len = 2];
  // Pagination parameters.
  worldmonitor.core.v1.PaginationRequest pagination = 3;
}

// ListWeatherStationsResponse contains the matching stations.
message ListWeatherStationsResponse {
  // The list of weather stations.
  repeated WeatherStation stations = 1;
  // Pagination metadata.
  worldmonitor.core.v1.PaginationResponse pagination = 2;
}

4. Define the service

Create proto/worldmonitor/weather/v1/service.proto:

syntax = "proto3";
package worldmonitor.weather.v1;

import "sebuf/http/annotations.proto";
import "worldmonitor/weather/v1/list_weather_stations.proto";

// WeatherService provides APIs for weather observation stations.
service WeatherService {
  option (sebuf.http.service_config) = {base_path: "/api/weather/v1"};

  // ListWeatherStations retrieves stations matching the given filters.
  rpc ListWeatherStations(ListWeatherStationsRequest) returns (ListWeatherStationsResponse) {
    option (sebuf.http.config) = {path: "/list-weather-stations"};
  }
}

5. Generate

make check   # lint + generate in one step

6. Implement the handler

Create the handler directory and files:

server/worldmonitor/weather/v1/
├── handler.ts                     # thin re-export
└── list-weather-stations.ts       # RPC implementation

server/worldmonitor/weather/v1/list-weather-stations.ts:

import type {
  WeatherServiceHandler,
  ServerContext,
  ListWeatherStationsRequest,
  ListWeatherStationsResponse,
} from '../../../../src/generated/server/worldmonitor/weather/v1/service_server';

export const listWeatherStations: WeatherServiceHandler['listWeatherStations'] = async (
  _ctx: ServerContext,
  req: ListWeatherStationsRequest,
): Promise<ListWeatherStationsResponse> => {
  // Your implementation here — fetch from upstream API, transform to proto shape
  return { stations: [], pagination: undefined };
};

server/worldmonitor/weather/v1/handler.ts:

import type { WeatherServiceHandler } from '../../../../src/generated/server/worldmonitor/weather/v1/service_server';

import { listWeatherStations } from './list-weather-stations';

export const weatherHandler: WeatherServiceHandler = {
  listWeatherStations,
};

7. Register the service in the gateway

Edit api/[[...path]].js — add the import and mount the routes:

import { createWeatherServiceRoutes } from '../src/generated/server/worldmonitor/weather/v1/service_server';
import { weatherHandler } from './server/worldmonitor/weather/v1/handler';

const allRoutes = [
  // ... existing routes ...
  ...createWeatherServiceRoutes(weatherHandler, serverOptions),
];

8. Register in the Vite dev server

Edit vite.config.ts — add the lazy import and route mount inside the sebufApiPlugin() function. Follow the existing pattern (search for any other service to see the exact locations).

9. Create the frontend service wrapper

Create src/services/weather.ts:

import {
  WeatherServiceClient,
  type WeatherStation,
  type ListWeatherStationsResponse,
} from '@/generated/client/worldmonitor/weather/v1/service_client';
import { createCircuitBreaker } from '@/utils';

export type { WeatherStation };

const client = new WeatherServiceClient('', { fetch: (...args) => globalThis.fetch(...args) });
const breaker = createCircuitBreaker<ListWeatherStationsResponse>({ name: 'Weather' });

const emptyFallback: ListWeatherStationsResponse = { stations: [] };

export async function fetchWeatherStations(network?: string): Promise<WeatherStation[]> {
  const response = await breaker.execute(async () => {
    return client.listWeatherStations({ network: network ?? '', countryCode: '', pagination: undefined });
  }, emptyFallback);
  return response.stations;
}

10. Verify

npx tsc --noEmit   # zero errors

Proto conventions

These conventions are enforced across the codebase. Follow them for consistency.

File naming

One file per message type: earthquake.proto, weather_station.proto
One file per RPC pair: list_earthquakes.proto, get_earthquake_details.proto
Service definition: service.proto
Use snake_case for file names and field names

Time fields

Always use int64 with Unix epoch milliseconds. Never use google.protobuf.Timestamp. Always add the INT64_ENCODING_NUMBER annotation so TypeScript gets number instead of string:

int64 occurred_at = 6 [(sebuf.http.int64_encoding) = INT64_ENCODING_NUMBER];

Validation annotations

Import buf/validate/validate.proto and annotate fields at the proto level. These constraints flow through to the generated OpenAPI spec automatically. Common patterns:

// Required string with length bounds
string id = 1 [
  (buf.validate.field).required = true,
  (buf.validate.field).string.min_len = 1,
  (buf.validate.field).string.max_len = 100
];

// Numeric range (e.g., score 0-100)
double risk_score = 2 [
  (buf.validate.field).double.gte = 0,
  (buf.validate.field).double.lte = 100
];

// Non-negative value
double min_magnitude = 3 [(buf.validate.field).double.gte = 0];

// Coordinate bounds (prefer using core.v1.GeoCoordinates instead)
double latitude = 1 [
  (buf.validate.field).double.gte = -90,
  (buf.validate.field).double.lte = 90
];

Shared core types

Reuse these instead of redefining:

Type	Import	Use for
`GeoCoordinates`	`worldmonitor/core/v1/geo.proto`	Any lat/lon location (has built-in -90/90 and -180/180 bounds)
`BoundingBox`	`worldmonitor/core/v1/geo.proto`	Spatial filtering
`TimeRange`	`worldmonitor/core/v1/time.proto`	Time-based filtering (has `INT64_ENCODING_NUMBER`)
`PaginationRequest`	`worldmonitor/core/v1/pagination.proto`	Request pagination (has page_size 1-100 constraint)
`PaginationResponse`	`worldmonitor/core/v1/pagination.proto`	Response pagination metadata

Comments

buf lint enforces comments on all messages, fields, services, RPCs, and enum values. Every proto element must have a // comment. This is not optional — buf lint will fail without them.

Route paths

Service base path: /api/{domain}/v1
RPC path: /{verb}-{noun} in kebab-case (e.g., /list-earthquakes, /get-vessel-snapshot)

Handler typing

Always type the handler function against the generated interface using indexed access:

export const listWeatherStations: WeatherServiceHandler['listWeatherStations'] = async (
  _ctx: ServerContext,
  req: ListWeatherStationsRequest,
): Promise<ListWeatherStationsResponse> => {
  // ...
};

This ensures the compiler catches any mismatch between your implementation and the proto contract.

Client construction

Always pass { fetch: (...args) => globalThis.fetch(...args) } when creating clients:

const client = new WeatherServiceClient('', { fetch: (...args) => globalThis.fetch(...args) });

The empty string base URL works because both Vite dev server and Vercel serve the API on the same origin. The arrow-function wrapper around globalThis.fetch is required for Tauri compatibility AND for the runtime fetch interceptor — fetch.bind(globalThis) is banned because it freezes a reference to the global fetch at module-init time, which bypasses any later interceptor (auth headers, request logging, retry shims) installed on globalThis.fetch. The arrow-function wrapper resolves globalThis.fetch on every call.

Generated documentation

Every time you run make generate, OpenAPI v3 specs are generated for each service:

docs/api/{Domain}Service.openapi.yaml — human-readable YAML
docs/api/{Domain}Service.openapi.json — machine-readable JSON

These specs include:

All endpoints with request/response schemas
Validation constraints from buf.validate annotations (min/max, required fields, ranges)
Field descriptions from proto comments
Error response schemas (400 validation errors, 500 server errors)

You do not need to write or maintain OpenAPI specs by hand. They are generated artifacts. If you need to change the API documentation, change the proto and regenerate.

​Prerequisites

​Adding an RPC to an existing service

​1. Define the request/response messages

​2. Add the RPC to the service definition

​3. Lint and generate

​4. Implement the handler

​5. Wire it into the handler re-export

​6. Verify

​7. Check the generated docs

​Adding a new service

​1. Create the proto directory

​2. Define entity messages

​3. Define request/response messages

​4. Define the service

​5. Generate

​6. Implement the handler

​7. Register the service in the gateway

​8. Register in the Vite dev server

​9. Create the frontend service wrapper

​10. Verify

​Proto conventions

​File naming

​Time fields

​Validation annotations

​Shared core types

​Comments

​Route paths

​Handler typing

​Client construction

​Generated documentation