Reference · SemText · Definitions & citations

`<sem-api-call>`

SemText element

The definition card for an endpoint. You write the operation name, HTTP method and path, then one sem-api-param child per parameter or response field; the page shows a table and machines read the same fields back.

Documents one API call's contract: method, endpoint, status and its parameters, as a card. The definition card for an endpoint. You write the operation name, HTTP method and path, then one sem-api-param child per parameter or response field; the page shows a table and machines read the same fields back. (on `sem-api-call`): required, string — the operation's display name.

(optional): string token — HTTP method, rendered uppercased, extraction records the authored spelling uppercased.

(required): string — path or URL template.

(optional): string — the documented response status ("200", "2xx", "201 Created" …).

per the global attribute catalog (conventions.md §2)

Example

sem-api-call.html

source

              
              <sem-api-call name="Create token" method="POST" endpoint="/oauth/token" status="200">
            
                Exchanges a grant for a token pair.
            
                <sem-api-param name="grant_type" in="body" type="string" required allowed="authorization_code,refresh_token">The grant to exchange.</sem-api-param>
            
                <sem-api-param name="code" in="body" type="string">The authorization code.</sem-api-param>
            
                <sem-api-param name="ttl" in="response" type="integer">Access-token lifetime in seconds.</sem-api-param>
            
              </sem-api-call>

render

Live render boots with JavaScript — the authored source is alongside.

Source: spec/schema/sem-api-call.md