2.15Import from an OpenAPI spec

What it does#

Give obsrvly an OpenAPI 3.x spec and it proposes one API monitor (2.3) for each GET or HEAD operation. You pick which to create. Nothing is created until you do. Your plan must include API monitors.

Import a spec#

1. Click + new monitor, then the api tab.
2. Click Have an OpenAPI spec? Import monitors from it.
3. Paste the spec into spec, or click Upload file. JSON and YAML both work. The file is read in your browser and sent as text.
4. Optional: fill in base url to check a different server, such as staging. It replaces every server URL in the spec. Include the base path: https://staging.example.com/v1.
5. Click Propose monitors.
6. Tick the operations to monitor. You can rename each one.
7. Optional: pick a region and the channels to notify. They apply to every monitor you create here.
8. Click Create N monitors. Each row shows created or why it failed. Click View monitors to see them on the dashboard.

What each proposal contains#

The list shows each proposal's method and path, its name and the status it expects.

Operations that are not proposed#

Some operations are listed under skipped, with the reason. Click it to open the list. An operation is skipped when:

• It uses a method other than GET or HEAD. Those may change data.
• It has a required parameter with no example or default, or a required cookie.
• It has no absolute server URL. Set base url to fix this.

A proposal that cannot be created as it is shows the reason and cannot be ticked. Examples: its host is localhost or a private IP address, or the create would refuse it.

Operations that need credentials#

A proposal marked needs credentials is one the spec says needs auth. Without credentials its first check would get a 401 and alert at once, so you cannot select it until you fill in the credentials header above the list. Save the token as a team secret first (chapter 8), then set the header to name it, such as Authorization : Bearer ${API_TOKEN}. Every selected monitor that needs credentials is created with that header; the others are created without it. If one endpoint needs a different header, edit that monitor after the import. See 8.3.

Plan limits#

When your plan caps monitors, the list says how many more it has room for. You cannot tick more than that. Each monitor is still checked against your plan when it is created, so a row can fail with a plan error.

Specs with external $refs#

obsrvly never fetches anything a spec points to. A $ref to another file or a URL is refused. Bundle the spec into one document first, then import that:

npx @redocly/cli bundle openapi.yaml -o bundled.yaml
# or
npx swagger-cli bundle openapi.yaml -o bundled.yaml -t yaml

$refs inside the same document, such as #/components/schemas/Pet, are fine.

Through the API#

ProposeMonitorsFromOpenApi returns the proposals. Send each one you keep to CreateApiMonitor as it is.

API=https://www.obsrvly.com/api/gw/monitor/obsrvly.v1.MonitorConfigService
jq -n --rawfile spec openapi.yaml '{spec: $spec}' |
curl -s "$API/ProposeMonitorsFromOpenApi" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" -d @-

Good to know#

• A spec can be at most 2 MiB. One import reads at most 500 operations. Past that the list says the spec was cut short. Split the spec to import the rest.
• Swagger 2.0 specs and Postman collections are not read. Convert them to OpenAPI 3 first.
• An import can be run again. It does not know which monitors you already have, so check for duplicates.