API

What an API records#

An API is a public or internal interface that groups Endpoints. Names are unique within an Organization.

For registration, see Record your first Catalog entry.

Base URLs#

Each item in base_urls takes a url and an optional label (up to 60 characters).

{
  "name": "Orders API",
  "handle": "orders-api",
  "base_urls": [
    {"url": "https://api.example.com/orders", "label": "Production"},
    {"url": "https://staging-api.example.com/orders", "label": "Staging"}
  ]
}

• url is an absolute http or https URL. Query strings, fragments, user info, and template variables such as {region} are not accepted, so expand them to actual values.
• The server normalizes and stores the addresses in input order and never connects to them. Addresses that are the same after normalization are rejected.
• When editing, omitting base_urls keeps the saved list, and sending [] clears it.

The Endpoint detail also shows the base URLs of its API.

Providing Service#

Name one Service that provides the API, or leave it empty. An Endpoint's providing Service follows its API. In the Web UI, use 제공 Service 변경 (change providing Service) under 제공 Service (Providing Service) on the API detail, and choose a Service or 제공 Service 없음 (no providing Service).

stly apis service get <api-id>
stly apis set-service <api-id> --service <service-id> --if-match '"ETag from the providing Service lookup"'
stly apis set-service <api-id> --none --if-match '"ETag from the providing Service lookup"'

The providing Service ETag is different from the API's own ETag. Use the etag from apis service get. A stale ETag returns HTTP 412.

OpenAPI document#

Each OpenAPI document links to one API. A document without a Repository appears under OpenAPI 문서 (OpenAPI document) on the API detail, which opens new source submission and the structly.yaml download. See OpenAPI sync for registration and import.

Endpoints and Systems#

stly endpoints list --api <api-id> --fields id,method,path
stly apis systems <api-id>

Record Endpoints in Endpoint and System compositions in System.

Delete#

An API cannot be deleted while it has Endpoints (HTTP 409 API_IN_USE). Move the Endpoints to another API or delete them first. The providing Service and a linked OpenAPI document do not block deletion. The document remains and only its API link is removed.

Authentication metadata#

Edit scheme definitions and common requirements in the API detail. Record public API key, HTTP, mutual TLS, OAuth, and OpenID Connect settings without tokens or passwords. Include this security field alongside the other API create or replacement fields:

{"security":{"schemes":{"token":{"type":"http","scheme":"bearer"}},"requirements":[{"token":[]}]}}

requirements: null means no common declaration; [] explicitly imposes no requirements. Array entries are alternatives (OR), schemes in one entry are combined (AND), and an empty object allows anonymous access. OAuth and OIDC values are scopes; other scheme values are role names. These declarations do not verify the running server.

Remove Endpoint references before removing a scheme. Omitting security on replacement preserves it; an object replaces it entirely. Use stly apis validate --operation create or --operation update <api-id> --if-match ... to validate without saving, following the CLI input rules.