rest-api-governance

name	rest-api-governance
description	Use when designing, adding, reviewing, or changing any LocalBridge or AIHub REST API. Applies to clawbot-facing HTTP endpoints, resource modeling, URI naming, HTTP methods, status codes, error shapes, pagination, filtering, and API versioning. Read the localBridge API design rules first and enforce them before coding.
metadata	{"author":"aiwithblockchain"}

REST API Governance

Use this skill for any task that involves:

• designing a new REST API
• changing an existing REST endpoint
• reviewing whether an endpoint is RESTful
• exposing LocalBridge capability via HTTP
• writing API docs for localBridge

Required first read

Before doing any design or code work, read:

• ../API_DESIGN_RULES.md

Load this reference only when you need the external rationale:

• references/microsoft-rest-summary.md

Workflow

1. Identify the resource.
2. Choose the URI using nouns and plural collection names.
3. Choose the HTTP method based on resource semantics.
4. Define request body, response body, and status codes.
5. Check pagination/filter/sort needs for collection endpoints.
6. Check whether the change is backward compatible.
7. Update API docs before or with code changes.

Hard rules

• Do not use verbs in URI paths unless there is a documented exception.
• Do not model task execution as ad-hoc RPC when a tasks resource fits.