# Bc Gov REST API

> BC Government REST API Development Standard — 8 mandated minimums for public APIs (RESTful architecture, HTTP verbs per RFC, single-resource URLs, multiple output formats, response metadata, error messaging, version numbers). Use when designing or reviewing public BC Gov APIs, writing OpenAPI specs, or evaluating API conformance.

- Skill: `rloisell/bc-gov-rest-api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rloisell/bc-gov-rest-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rloisell/bc-gov-rest-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: rloisell (https://skillmd.com/u/rloisell)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rloisell/bc-gov-rest-api

---


# BC Gov REST API Development Standard

The **REST API Development Standard** (effective 2015-04-01) requires that all *new public
APIs* in BC Government MUST be designed and developed according to RESTful architecture
principles per Fielding's dissertation, adapted to BC Gov mandated minimums. Internal APIs
SHOULD follow the same pattern.

> The intent is not to prescribe a re-architecture of existing APIs or limit development to
> the prescribed minimums, but to ensure BCGov APIs behave consistently and balance a truly
> RESTful interface with positive developer experience (DX).

## Mandated minimum attributes

| # | Mandate | Notes |
| --- | --- | --- |
| 1 | Public APIs **MUST** expose RESTful interfaces. | RPC-over-HTTP, SOAP, GraphQL-only do not satisfy this for public APIs. |
| 2 | Internal APIs **SHOULD** expose RESTful interfaces. | Same pattern recommended for internal consistency. |
| 3 | HTTP verbs **MUST** be used per HTTP/1.1 (RFC 7231). Only `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `TRACE`, `OPTIONS` are permitted. | No verb tunnelling (e.g., `POST /resource/delete`). |
| 4 | A URL **MUST** identify only a single resource. | No multi-resource fan-out URLs. |
| 5 | APIs **SHOULD** allow multiple output formats. | Recommended minimum: JSON and/or XML via `Accept` content negotiation. |
| 6 | Metadata **MUST** be described in a variable in the response. | Minimum fields: 6.1 creation date-time (ISO 8601 with timezone), 6.2 license(s) relevant to the dataset payload. |
| 7 | APIs **MUST** provide relevant error messaging. | Use HTTP status codes correctly; include machine-parseable error body. |
| 8 | APIs **MUST** be released with a version number. | URL or header versioning are both acceptable; version each breaking change. |

## Verb conformance reference

| Verb | Idempotent | Safe | Typical use |
| --- | --- | --- | --- |
| `GET` | Yes | Yes | Read; cacheable |
| `HEAD` | (not in standard's allow-list) | (n/a) | \u2014 |
| `POST` | No | No | Create; non-idempotent action |
| `PUT` | Yes | No | Replace |
| `PATCH` | No (recommended idempotent in practice) | No | Partial update |
| `DELETE` | Yes | No | Remove |
| `TRACE` | Yes | Yes | Diagnostic loop-back |
| `OPTIONS` | Yes | Yes | CORS preflight; capability discovery |

## Response metadata template (Mandate #6)

```json
{
  "metadata": {
    "createdAt": "2026-04-30T14:30:00-07:00",
    "license": [
      {
        "name": "Open Government Licence \u2013 British Columbia",
        "url": "https://www2.gov.bc.ca/gov/content/data/open-data/open-government-licence-bc"
      }
    ],
    "version": "1.2.0"
  },
  "data": [ /* ... */ ]
}
```

ISO 8601 with timezone offset is required (Control #6.1.1, also enforced by the BC Government
date and time standard). UTC zulu (`Z`) suffix is also acceptable.

## Common BC Gov anti-patterns

| Anti-pattern | Why it violates the standard |
| --- | --- |
| `POST /api/users/12/delete` | Verb tunnelling \u2014 violates Mandate #3 (use `DELETE`). |
| `GET /api/v1/users-and-orders/12` | URL identifies two resources \u2014 violates Mandate #4. |
| Returning HTTP 200 with `{ "error": "not found" }` body | Misuses status code \u2014 violates Mandate #7. |
| Releasing v2 in place by overwriting v1 routes | Breaks Mandate #8 \u2014 ship `/v2/` (or `Accept-Version: 2`). |
| Omitting metadata wrapper | Violates Mandate #6 \u2014 license + creation timestamp are minimum. |

## Where to apply

This standard applies when an information system, API, or service is **being developed by,
or on behalf of**, the Province of British Columbia. CIO-level exemption is required for
non-compliance.

## Companion standards

| Topic | Standard |
| --- | --- |
| Authentication for the API | IMIT 6.13 + DIAM/Common SSO (see `bc-gov-iam`) |
| API hosting network zone | IMIT 6.13 (typically Low/DMZ for public APIs with WAF) |
| API security controls (input validation, OWASP) | Security Standard for Application and Web Development and Deployment |
| Data classification of API payload | IMIT 6.18 ISCF |
| Database providing the data | `bc-gov-database-security` skill |