Adding API Endpoints

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 through the domain gateway in api/seismology/v1/[rpc].ts. createSeismologyServiceRoutes() picks up the new RPC automatically — no route-table or vite.config.ts edits are needed.

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. Add the per-domain edge gateway

Create api/weather/v1/[rpc].ts as the thin Edge entry point for this service:

export const config = { runtime: 'edge' };

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

export default createDomainGateway(
  createWeatherServiceRoutes(weatherHandler, serverOptions),
);

There is no repository-wide catch-all gateway file or shared route array to edit. Each service owns its api/<domain>/v1/[rpc].ts gateway, and the generated create<Service>Routes(...) function enforces the RPC path names and HTTP annotations for that domain.

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

MCP exposure decision

Every new public OpenAPI operation needs an explicit MCP decision before review. MCP is a curated agent surface, not a 1:1 mirror of REST: expose operations that are safe, predictable, and useful as tools; keep REST-only operations documented when they mutate state, spend per-call LLM or upstream budget, or need manual cache-key review.

Use this checklist for each new or changed RPC:

• Decide whether this operation should be exposed to MCP.
• If yes, identify the owning MCP tool and add the exact METHOD /api/... entry to that tool's _apiPaths.
• If cache-backed, confirm the tool has the right _cacheKeys / _coverageKeys, freshness metadata, and seed-meta:<key> health coverage.
• If no, add or update the tests/mcp-api-parity.test.mjs exclusion with the matching category prefix and a concrete reason.
• If fetch-on-miss, include one enforced secondary signal (high-cardinality-input, paid-upstream, or llm-cost) and name the upstream cost, cardinality, and tier policy that makes open MCP exposure unsafe for now.
• If mutating or llm-passthrough, document the separate threat/cost model before proposing an MCP wrapper.
• Run ./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs and include the result in the PR.

A covered operation is declared in a tool _apiPaths entry. For REST-only operations, the parity test accepts these exclusion categories:

The MCP reference docs render the current _apiPaths coverage table in MCP Overview. The parity test is canonical for the current covered/excluded split, so do not rely on stale counts in a PR description.

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:

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.