Publish an API and call it

Four kinds of document describe an API:

Write the API#

The invoices API puts a gateway in front of the ERP’s invoice endpoints:

apiVersion: weik.io/v1
kind: api
metadata: { name: invoices, project: finance }
spec: { displayName: Invoice API, prefix: /invoices }
---
apiVersion: weik.io/v1
kind: api-version
metadata: { name: v1, project: finance, api: invoices }
spec:
  type: proxy
  rateLimit: { permitLimit: 600, window: 1m }
  routes:                                   # YARP RouteConfig, as it is
    - RouteId: pending
      Match: { Path: "/{**rest}" }
      ClusterId: erp
  clusters:                                 # YARP ClusterConfig, as it is
    - ClusterId: erp
      LoadBalancingPolicy: RoundRobin
      Destinations:
        erp: { Address: "{{erp-url}}/api/invoices" }

routes and clusters are the configuration of YARP, the .NET reverse proxy that runs inside the gateway, unchanged, so every YARP feature is available and YARP’s documentation applies. The upstream’s address is a placeholder, so devtest and production send the calls to their own ERP. Upstreams and routes has the rest of the version’s fields.

weikio init invoices --kind api --project finance writes a starting point: the API and a proxy version pointing at an example service until the environment has a value for its address.

Apply it#

$ weikio apply -f ./finance/apis/

Target: https://hub.example, project finance (from finance/project.yaml)
api finance/invoices created
api-version finance/invoices@v1 created (type proxy, rate limit 600/1m)
api-version finance/bank-notifications@v1 created (type webhook, channel bank-notification-received)
api-deployment devtest/finance/invoices@v1 created
api-subscription devtest/finance/partner-y created
Gateways updated in: devtest.

The backend fills in the placeholders and checks the routes and clusters with YARP’s own validator when you apply, so a broken route fails here and not at the gateway. The folder above also had the devtest deployment and a devtest subscription, so devtest serves the API at once.

Deploy it#

weikio api deploy serves the version as it stands on an environment’s gateway. weikio api promote serves in production exactly the definition devtest tested:

$ weikio api deploy finance/invoices@v1 --env devtest
$ weikio api promote finance/invoices@v1 --from devtest --to production -y

Target: https://hub.example, project finance (argument), environment production (--to)
api-deployment production/finance/invoices@v1 created (gateways internal, definition 3f9a0c1e2b4d, revision 31)
Served at https://api.example.com/invoices/v1 (gateway internal).

The address is the gateway’s hostname, the API’s prefix and the version: https://api.example.com/invoices/v1. Each environment has its own hostnames, so devtest serves the same API at https://api-test.example.com/invoices/v1. The gateway gets a new route table within seconds and keeps serving the last one it had if the backend is down.

Call it#

A caller needs a subscription. Create one with an API key, which the CLI prints once:

$ weikio subscription create finance/partner-x --env production --api invoices --type apikey --rate-limit 60/60s -y

Target: https://hub.example, project finance (argument), environment production (--env)
api-subscription production/finance/partner-x created (gateway internal, type apikey, APIs invoices, rate limit 60/1m)

To rotate the key later:
  weikio subscription rotate-key finance/partner-x --env production

API key (shown once): ****************************************

Then call the API with the key in the X-Api-Key header:

$ curl -H "X-Api-Key: $PARTNER_KEY" https://api.example.com/invoices/v1/pending

A call with no credential, or one no subscription of the API has, gets 401 with an empty body and a WWW-Authenticate header for each kind of credential the API’s subscriptions accept. Every response carries a traceresponse header, which finds the call’s trace. Watching the calls shows where.

Edit and deploy again#

A deployment serves the definition it pinned when it was deployed. After you change the version and apply it, the apply prints each environment that serves an older definition, with the line that deploys the new one:

finance/invoices@v1 in devtest serves an older definition. Deploy it with: weikio api deploy finance/invoices@v1 --env devtest

Values and secrets aren’t pinned, so a changed erp-url reaches the gateway at once.