Endpoint

What an Endpoint records#

Write Schemas in JSON Schema 2020-12. method accepts GET, HEAD, POST, PUT, DELETE, OPTIONS, PATCH, and TRACE.

Web UI#

In Endpoints → 새 Endpoint (New Endpoint), enter the details and select Endpoint 등록 (Register Endpoint). The detail also shows the base URLs of its API and the Workflows that call this Endpoint.

Endpoint, Parameter, and Header each record their own deprecated value. The 사용 중단 예정 (deprecated) label in lists and details does not propagate to other locations or change whether a value is required. The same key in a Schema is an annotation for that Schema. Omitting deprecated from update JSON replaces an existing true with false, so include the current value to preserve it.

stly#

Here is an example endpoint.json. Each {order_id} in the Path needs a Path Parameter with the same name, and Path Parameters are required: true.

{
  "api_id": "4pkKFh2ojXs",
  "method": "GET",
  "path": "/orders/{order_id}",
  "summary": "Get order details",
  "parameters": [
    {"name": "order_id", "location": "path", "required": true, "schema_definition": {"type": "string", "format": "uuid"}}
  ],
  "responses": [
    {"status_key": "200", "description": "Order", "contents": [
      {"media_type": "application/json", "schema_definition": {"type": "object", "required": ["id", "status"], "properties": {"id": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "paid", "cancelled"]}}}}
    ]},
    {"status_key": "404", "description": "Order not found"}
  ],
  "examples": [
    {"name": "Paid order",
     "request_example": {"path_parameters": [{"name": "order_id", "value": "50ECYsM55Ec"}]},
     "response_example": {"status_code": 200, "body": {"media_type": "application/json", "value": {"id": "50ECYsM55Ec", "status": "paid"}}}}
  ]
}

Check it on the server before saving, then create it.

stly endpoints validate --operation create --input endpoint.json
stly endpoints create --input endpoint.json
stly endpoints list --api 4pkKFh2ojXs --fields id,method,path,summary

endpoints list --q searches the Path, summary, and description, and is case-sensitive.

Examples#

Each item in examples is a name plus a pair of request and response examples.

• A request example contains path_parameters, query_parameters, headers, and body.
• A response example contains a concrete integer status_code, headers, and body.
• body uses the format {"media_type": "...", "value": ...}. Omit body when there is no body.
• You can also record error response examples. Examples are not checked against the Schema.

External References#

Record code and external document sources in external_references. Each item needs at least one of url and external_id.

{"external_references": [{"label": "Source code", "url": "https://github.com/acme/orders-service/blob/3f2c1a9/src/routes/orders.ts#L10", "external_id": ""}]}

URLs pinned to a commit SHA are recommended. When editing, omitting the field keeps the saved values, and [] clears them.

Calling Workflows#

stly endpoints workflows <endpoint-id>

Returns the Workflows whose Steps call this Endpoint. Record Workflows in Workflow.

Endpoints with a spec source#

Endpoints created by OpenAPI sync show 스펙 출처 (spec source) and a link to the source document in the Web UI. You can edit their fields directly, including Method, Path, requests, and responses. Values that differ from the source are reported as changes in the next plan. The API membership follows the source document's API and cannot be changed (HTTP 409 ENDPOINT_SPEC_MANAGED). To move the Endpoint to another API, release the source first.

The API 제공 Service (API providing Service) column in the Endpoint list shows the providing Service of the Endpoint's API.

Delete#

An Endpoint called by a Workflow Step cannot be deleted (HTTP 409 ENDPOINT_IN_USE). Check the calling Workflows with stly endpoints workflows and change their Steps first.

Authentication declarations and effective requirements#

An Endpoint security value of null inherits the API declaration; an array overrides it. [] explicitly imposes no requirements, while [{}] allows anonymous access. Named schemes resolve within the connected API, so an API connection is required. Omitting the field on replacement preserves its stored value.

stly endpoints security <endpoint-id>

The effective view returns the declaration origin, requirements, and referenced scheme definitions. Undeclared does not mean authentication is unnecessary. Its ETag cannot be used to update the Endpoint.

Review the effective requirements before and after changing or clearing the API in the Web editor. Inheritance follows the destination API; removing the connection leaves no inherited declaration. Named references in an override must resolve in the destination API and must be removed when disconnecting. Releasing only the spec source preserves authentication declarations and API membership.