Skip to content
Sign in

How-to

API checks

Updated

On this page

API checks call your API's GET endpoints and compare each answer with your API spec. Publishing a spec takes about 5 minutes if your framework can write one for you.

What an API spec is

An API spec (an OpenAPI document) is one JSON or YAML file that lists your endpoints, the parameters each one takes, and the answers it can give: the status codes and the shape of each response body. Zof reads it to know what a correct answer looks like.

Zof reads OpenAPI 3.0, OpenAPI 3.1 and Swagger 2.0, as JSON or YAML.

Where Zof looks for it

Zof looks on the address you check, in this order, and uses the first spec it finds:

PathExample
/openapi.jsonhttps://shop.example.com/openapi.json
/openapi.yamlhttps://shop.example.com/openapi.yaml
/swagger.jsonhttps://shop.example.com/swagger.json
/v3/api-docshttps://shop.example.com/v3/api-docs
/api-docshttps://shop.example.com/api-docs

A project can also name its spec as its context file: a URL on the same address, or a public https URL elsewhere. Zof never sends your credentials or headers to a spec on another host.

If none of these answers with a spec, the run says "No API spec found at this address" and checks nothing. A page that answers every address with the same HTML (common for single-page apps) is not a spec, and Zof doesn't treat it as one.

Publish a spec

Many frameworks write the spec for you:

  • FastAPI serves /openapi.json by default.
  • Spring Boot with springdoc serves /v3/api-docs.
  • NestJS, Express and others can serve one with a Swagger or OpenAPI package.

Otherwise, write the file by hand and serve it as a static file at /openapi.json. Keep the paths in the spec the same as the ones your site answers, for example /api/products.

If your API lives on another address than your site, check that address instead: start the run with the API's address. Only a company admin can change a repository's saved address.

What Zof calls

  • Only GET endpoints, one request each, so nothing on your site changes. The Run page refuses POST, PUT, PATCH and DELETE.
  • Only on the address you check. Redirects to another host are not followed.
  • Each answer is checked for a status the spec documents, the documented content type, and a body that matches the spec's schema.

Check that it worked

Open /openapi.json (or the path your framework uses) on your address in a browser. You should see JSON or YAML that starts with "openapi" or "swagger", not your site's home page. Then run API checks again from the Run page: each endpoint shows as passed, or as a problem that names what didn't match.

Next steps