Skip to main content

API services

An API service is a published asset that groups several key-gated REST endpoints. External systems call an endpoint with a dk_… key; no Honeyframe account is needed. See API Services for the serving model.

Create a service​

from honeyframeapi import lookup_endpoint, model_endpoint, sql_endpoint

svc = client.create_api_service(
    "store-serving", "Store serving",
    endpoints=[
        lookup_endpoint("store", "marts.dim_store", "store_key"),
        sql_endpoint("top_stores", {
            "source": {"schema": "marts", "table": "fact_orders"},
        }),
        model_endpoint("churn_risk", model_id=12),
    ],
    publish=True,
)

API services are project-scoped: the client needs a project_id, or pass project_id= to create_api_service. project.create_api_service(...) does the same within a project handle. The service is created as a draft unless publish=True; draft endpoints are not callable. client.get_api_service(asset_id) opens an existing service.

Endpoint builders​

BuilderEndpoint
sql_endpoint(id, query)Serves a data-API query; query is the data-API query config ({source: {schema, table}, columns, filters, joins, pagination}).
lookup_endpoint(id, dataset, key_column, *, key_param="id", columns=None, max_results=100)Returns rows of dataset (schema.table) whose key_column equals the request's key_param value.
model_endpoint(id, *, model_id)Online predictions from a saved model.
function_endpoint(id, handler)A governed Python function. Not served yet: the serving runtime answers 501 for this kind.

SQL and lookup endpoints use the data-API query engine, so masking, filters and joins behave as they do for a data API.

Edit the endpoints​

svc.add_endpoint(lookup_endpoint("store_by_code", "marts.dim_store", "store_code",
                                 key_param="code"))
svc.set_endpoints([lookup_endpoint("store", "marts.dim_store", "store_key")])
svc.endpoints            # the current endpoint dicts
svc.publish()            # push the edited draft live

add_endpoint(endpoint, *, publish=False, change_note="") adds an endpoint, or replaces the one with the same id, and saves the config. Editing does not republish: pass publish=True or call publish(). unpublish() takes the service offline. As a published asset, a service also has versions(), rollback(version) and diff_versions(a, b).

Mint a key​

key = svc.create_key(name="mobile-app", allowed_endpoints=["store", "churn_risk"])
print(key.key)           # the dk_… secret — shown ONCE, store it now

create_key(*, name="", allowed_endpoints=None, rate_limit=100, expires_days=90, masking_level="masked", allowed_columns=None, sensitivity_max="medium"). allowed_endpoints=None allows every endpoint. The expiry and sensitivity defaults (0.1.8+) are explained under Authentication → Data-API keys; expires_days=0 makes a key that never expires.

Call an endpoint​

row = svc.call("store", api_key=key.key, method="GET", params={"id": 12})

pred = svc.call("churn_risk", {"features": {"tenure_months": 34, "plan": "pro"}},
                api_key=key.key)
print(pred["predictions"])

call(endpoint_id, payload=None, *, api_key, params=None, method="POST") sends the key in the X-API-Key header to the service's public serving route. Use method="GET" with params for SQL and lookup endpoints (a lookup's key is a query parameter named by its key_param), and the default POST with a payload for model endpoints ({"features": {...}} for one row, or {"rows": [...]}).

To try an endpoint before minting a key, svc.test(endpoint_id, payload) runs the same dispatch with your own session instead of a key, unmasked for admins.

From another language, call the same route over HTTP:

curl -s -H "X-API-Key: $DK_KEY" \
  "https://platform.your-domain.com/api/service/store-serving/store?id=12"

Verified against honeyframeapi 0.1.8.