Stationworks Permits API

This section is published verbatim on the docs site. It is what we promise, and it binds every future change to a /v1/ path.

We may, without notice:

• Add fields to any response object.
• Add new values to any enum (state, fireDanger, and any later one).
• Add endpoints.
• Return null for any field documented as nullable, at any time. Weather and air quality are nullable because they come from third parties.
• Add or remove entries in a list (a district adds or retires a status).

We will never, within v1:

• Remove or rename a field, or change its type.
• Change the meaning of an enum value.
• Change or reuse an id. An id names one thing forever.
• Change the URL of an endpoint.
• Remove a value from an enum.

Consumers must therefore:

• Ignore fields they do not recognise.
• Treat an unrecognised enum value as "unknown" and still render the rest.
• Store ids, never labels or display names.
• Expect an id to disappear from a list (a retired status or district).

A change that breaks a "never" rule ships as /v2/<product>/… alongside v1. v1 then gets a published retirement date. Versions are per product: /v2/permits says nothing about /v1/water.

Retiring a version. A version keeps working for at least 12 months after its successor ships. During that window its responses carry the standard Deprecation and Sunset headers, the docs site's changelog records the dates, and every registered consumer is emailed. Additions are also recorded in the dated changelog.

Reserved: a dated version header. If breaking changes ever become frequent, clients may later pin behavior with an optional Api-Version: YYYY-MM-DD request header. A request without it always gets the current v1 behavior, so adding the header breaks nobody.

What an id is. A UUID copied from the database row: core.agency.id for an agency, permits.burn_status.id for a status, permits.permit_type.id for a permit. These authorize nothing. They are unlike the permit and application UUIDs, which are bearer credentials (Invariant 5's capability surfaces) and must never appear here.

Status ids and renames. A status row's id holds while the row is active. Config documents key status rows by slug, so renaming a slug in a document retires the old row and creates a new one. To a consumer, that is one status disappearing and another appearing. That is allowed by the contract above. No other path renames a status slug today: the console and permits set never change an existing row's slug.