IF Commons GitHub

surfaces/rest/openapi

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0014-rest-surface FR-001, 0014-rest-surface FR-002, 0014-rest-surface FR-003

The REST surface, as a skeleton (commons headless 0014-rest-surface): the OpenAPI 3.1 document of a program, generated from governance for the caller's tier. One path for each command that the tier may see, that may come through the rest channel and that is not for a person alone: GET for a command that only reads (its options are query parameters), POST for one that changes something (its options and operands are the JSON body); the operation says its effect, its tier and whether it is safe to repeat, and the same refusals as the tool server are the 403 and 409 of every operation.

Pure: a program, a tier and the facts of the API give a JSON value. There is no server here: the routing of a request to a command, the authentication of the caller (which gives the tier) and the transport are Planned (0014 Out of scope), and the document is what they will be held to.

import { pathOf } from "./openapi.ts";
pathOf(["server", "list"]); // "/v1/server/list"

Source: commons/headless/src/surfaces/rest/openapi.ts

6 of 7 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

pathOffunction
function pathOf(words: readonly string[]): string

The path of a command: /v1/ and its words.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

operationIdfunction
function operationId(program: string, words: readonly string[]): string

The identifier of an operation: the program's name and the words of the command joined by underscores.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

exposedfunction
function exposed(p: Placed): boolean

Whether a command is an operation: it may come through the rest channel and it is not for a person alone.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

methodOffunction
function methodOf(p: Placed): "get" | "post"

The method of an operation: GET where the command only reads, POST where it changes something.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

REFUSAL_REASONSconst
const REFUSAL_REASONS: readonly string[]

The reasons a call is refused, the same as the tool server's: a closed set a client may match on.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

ApiInfotypeno test imports it
type ApiInfo = { readonly title?: string; readonly version?: string };

What the document says of the API besides the commands.

openApiOffunction
function openApiOf(program: Program, tier: TierName, info?: ApiInfo): Json

The OpenAPI 3.1 document of a program for a caller of a tier.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.