api-docs

Files (5)

• SKILL.md
• api-template.md · assets/
• rpc-template.md · assets/
• webhook-template.md · assets/
• type-notation.md · references/

SKILL.md (first lines)

# API documentation

API documents define interfaces between actors or components. They record
decided interface contracts; they do not decide component responsibilities,
workflow sequencing, durable state, or implementation.

Prose quality follows `prose-discipline`. Vocabulary and information ownership
follow `vocabulary-control`. A fact is normative in exactly one document;
dependent documents reference it instead of restating or weakening it.

## Document types

One file, one interface type.

| Type     | Governs                                                 |
| :------- | :------------------------------------------------------ |
| HTTP API | request/response operations exposed over HTTP           |
| RPC      | operations exposed by one component to internal callers |
| webhook  | inbound messages delivered to one component over HTTP   |

Use the corresponding template from `## Assets`.

The transport does not determine the document type by itself. A webhook remains
a webhook because its contract is inbound message delivery, even though it uses
HTTP. An RPC surface remains RPC when its contract is component-to-component
invocation, even when the underlying transport uses HTTP.

## Scope

An API document defines only facts intrinsic to the interface it governs.

Typical interface facts include:

* permitted callers or senders;
* exposed operations or accepted messages;
* routes or operation names;
* request and response shapes;
* authentication requirements at the interface;
* operation or message authorization;
* validation performed at the interface;
* acknowledgement or response semantics;
* retry, replay, and idempotency requirements;
* failures visible at the interface.

An API document does not redefine:

* component boundaries;
* caller or sender responsibilities outside the interface;
* workflow sequencing beyond one operation or delivery;
* durable state models;
* implementation frameworks;
* deployment topology;
* internal behaviour that is not observable through the interface.

Those facts remain in their owning documents.

## Authority

Authentication establishes identity. It does not by itself authorize an
operation or message.

Where authorization exists at an interface, state what authenticated identity
is authorized to perform. Do not infer authorization from transport security,
network placement, or successful authentication.

Do not invent callers, senders, operations, messages, identifiers, fields,
acknowledgements, or error classes to make an interface appear complete.

Record decided contract only.

## Message and field discipline

Request, response, and message shapes contain only information required by the
interface contract.

Do not add generic metadata merely because a framework commonly supplies it.
Examples include:

* request identifiers;
* correlation identifiers;
* event identifiers;
* delivery identifiers;
* retry counters;
* timestamps;
* version fields.

Include such values only when the decided interface requires them.

A field carries one established meaning. API documents use canonical vocabulary
and do not introduce aliases for terms owned elsewhere.

## Validation

State validation performed at the documented interface.

Separate:

* malformed input;
* failed authentication;
* failed authorization;
* contract validation;
* application or state conflict;
* dependency or service failure;

only where those distinctions exist in the decided contract.

An interface must not repair malformed authority-bearing input unless that
behaviour is explicitly part of the contract.

Validation performed later in a workflow belongs to that workflow or its
owning component, not to the API document.

## Failure semantics

Failures describe what the interface can establish.

Do not:

* convert dependency failure into an authoritative negative result;

From iamthenop/infurnet-skills, MIT.

More from iamthenop/infurnet-skills