Skip to main content

:::note Generated reference Generated from honeyframeapi 0.1.8 — do not edit by hand. :::

honeyframeapi.api_service

API Service handles — group several key-gated endpoints under one published asset, then call them with a minted key.

An API Service is a published asset (asset_type='api_service') whose config.endpoints is a list of endpoint dicts. Build it from the endpoint helpers and call an endpoint with a dk_… key:

from honeyframeapi import lookup_endpoint, model_endpoint

svc = client.create_api_service(
    "orders-serving", "Orders Serving",
    endpoints=[
        lookup_endpoint("customer", "marts.dim_customer", "customer_key"),
        model_endpoint("churn_risk", model_id=12),
    ],
    publish=True,
)
key = svc.create_key(name="app", allowed_endpoints=["churn_risk"])
out = svc.call("churn_risk", {"features": {"tenure_months": 34}}, api_key=key.key)
print(out["predictions"])

sql/lookup endpoints reuse the data_api query engine (masking, filters, joins); model endpoints score a saved model online; function endpoints are not served yet (501). A key can be scoped to a subset of endpoints via allowed_endpoints.

class APIService​

Bases: PublishedAsset

A published API service. Inherits publish/unpublish/update/ reload from PublishedAsset; adds endpoint management + serving.

APIService.endpoints​

property

endpoints: list

The endpoint dicts (reloads if the config isn't cached).

APIService.add_endpoint()​

add_endpoint(endpoint: dict, *, publish: bool = False, change_note: str = '') -> APIService

Add (or replace, by id) one endpoint and save the config.

endpoint comes from sql_endpoint / lookup_endpoint / model_endpoint / function_endpoint. Read-modify-writes the full config. Editing the draft does NOT republish — pass publish=True (or call publish) to push it live.

APIService.set_endpoints()​

set_endpoints(endpoints: list, *, change_note: str = 'set endpoints') -> APIService

Replace the whole endpoints list and save.

APIService.publish()​

publish() -> dict

APIService.unpublish()​

unpublish() -> dict

APIService.create_key()​

create_key(*, name: str = '', allowed_endpoints: Optional[list] = None, rate_limit: int = 100, expires_days: Optional[int] = API_KEY_DEFAULT_DAYS, masking_level: str = 'masked', allowed_columns: Optional[list] = None, sensitivity_max: str = DEFAULT_SENSITIVITY_MAX) -> ApiKey

Mint a dk_… key for this service, optionally scoped to a subset of endpoints (allowed_endpoints=None → all). The full secret is on the returned object's .key — shown ONCE. Same defaults as PublishedAsset.create_api_key: 90-day expiry (0 = never) and sensitivity_max="medium".

APIService.call()​

call(endpoint_id: str, payload: Optional[dict] = None, *, api_key: str, params: Optional[dict] = None, method: str = 'POST') -> Any

Call an endpoint via the public serving route with a minted key.

Sends X-API-Key: <api_key> to /api/service/{key}/{endpoint}. Use method='GET' + params for sql/lookup endpoints (the lookup key is a query param), or the default POST + payload for model endpoints ({'features': {...}} or {'rows': [...]}).

APIService.test()​

test(endpoint_id: str, payload: Optional[dict] = None) -> dict

Builder dry-run (JWT auth, admin-unmasked, no key) — the same dispatch the serving route uses, for trying an endpoint before minting a key.

Functions​

sql_endpoint()​

sql_endpoint(id: str, query: dict) -> dict

A SQL endpoint. query is a data_api query config ({source:{schema,table}, columns, filters, joins, pagination}).

lookup_endpoint()​

lookup_endpoint(id: str, dataset: str, key_column: str, *, key_param: str = 'id', columns: Optional[list] = None, max_results: int = 100) -> dict

A lookup endpoint: fetch rows from dataset (schema.table) where key_column equals the request's key_param value (default id).

model_endpoint()​

model_endpoint(id: str, *, model_id: int) -> dict

An online model-prediction endpoint over a saved model (model_id).

function_endpoint()​

function_endpoint(id: str, handler: str) -> dict

A governed function endpoint (admin-curated python handler body). NOTE: not served yet — the serving runtime returns 501 for this kind.

Verified against honeyframeapi 0.1.8.