What an OpenAPI file is, and why it saves weeks

When you ask a software vendor whether their product "has an API", the useful follow-up question is: do you have an OpenAPI file? The answer often decides whether an integration takes an afternoon or several weeks.

The short version

An OpenAPI file (older versions are called Swagger) is a document that describes an API in a structured way. It is usually a YAML or JSON file. It lists:

• The server address, such as https://api.example.gov/v2.
• How to sign in: an API key in a header, a bearer token, OAuth, or basic sign-in.
• The paths, such as /permits and /permits/{id}, and what each one does.
• The fields each record has, with their types.
• Parameters for filtering and paging.

It is the API's manual, written so both people and software can read it.

What one looks like

Here is a tiny piece of one:

openapi: 3.0.3
info:
  title: Permits API
servers:
  - url: https://api.example.gov/v2
paths:
  /permits:
    get:
      summary: List permits
      parameters:
        - name: updated_since
          in: query
          schema: { type: string, format: date-time }
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

Even without reading every line, you can see the address, the list path, a "changed since" filter and how sign-in works.

Why it saves weeks

Without an OpenAPI file, integration starts with reading documentation pages, emailing the vendor and testing calls by hand to learn what a record actually looks like. Each question can take days to answer.

With the file, most of those questions are answered up front:

• No guessing at field names. The fields and their types are listed.
• No guessing at sign-in. The security scheme says exactly what to send.
• Fewer surprises in paging. Parameters for page size and offsets are described.
• A shared reference. Your team and the vendor are looking at the same document.

Where to find it

• Look for links named "OpenAPI", "Swagger", "API spec" or "openapi.json" in the developer documentation.
• Many APIs serve it at a path such as /openapi.json, /swagger.json or /v3/api-docs.
• If you can't find it, ask your vendor's support team. Many have one even if it isn't published.

Reading one without being a developer

You don't need to write code to get value from the file. Open it in any text editor or an online viewer and look for three things: the servers section (where the API lives), the securitySchemes section (how it signs in), and the paths section (what you can read and write). Those three answer most early project questions.

What a file doesn't tell you

An OpenAPI file is a description, and descriptions can be incomplete. It won't tell you:

• Which record types and statuses your agency uses.
• Whether your account has permission to call each path.
• How the vendor limits the number of calls per minute.
• Whether example values match real data.

That's why the next step after importing a file is always to look at real records. See data inspection before you integrate.

Swagger 2 vs OpenAPI 3

You may see both names. Swagger 2 is the older format; OpenAPI 3 is its successor and is now the more common one. They describe the same things with slightly different layouts. Most tools, SentraBridge included, read either one, so you don't need to convert anything before importing it.

Turning the file into a connector

In SentraBridge, you can upload an OpenAPI 3 or Swagger 2 file, in YAML or JSON, and it builds a connector for that client: the address, sign-in, resources, fields and paging. You add the credentials, and the connector shows up in the designer like any pre-built one.

No file at all? SentraBridge also connects to any REST or JSON API with just an address, a sign-in method and the paths you want. The file simply gets you there faster. Browse the full list of pre-built connectors.