Reading an OpenAPI document before you write code
Answer in brief
An OpenAPI document is the machine-readable contract of an HTTP API. Read it before you write code, starting with servers, then paths and parameters, then the response schemas and the error responses. Ten minutes with the document tells you more about a company data API than its landing page, and it shows what the docs leave out.
Disclosure. This site is published by Coragrid, the operator of CompanyRegistryAPI.com, and promotes it. “Best” is our editorial choice, not a measured ranking. Other products are described only from their own official pages. How we choose
What an OpenAPI document is
The OpenAPI Specification describes itself as a standard, language-agnostic interface description for HTTP APIs that lets humans and computers discover a service’s capabilities without its source code or traffic inspection. For a company data API, the document is where field names, required parameters and error responses are stated precisely.
Fetch it and get an outline
The free CompanyRegistryAPI.com API publishes its document at a stable URL. Download it and list what it contains:
curl -s https://companyregistryapi.com/api/openapi.json -o openapi.json
python3 - <<'PY'
import json
doc = json.load(open("openapi.json"))
print(doc["openapi"], doc["info"]["title"])
for server in doc.get("servers", []):
print("server:", server["url"])
for path, item in doc["paths"].items():
for method, op in item.items():
if method in {"get", "post", "put", "patch", "delete", "query"}:
print(method.upper(), path, sorted(op.get("responses", {})))
PY
For this API the outline shows one server, three GET paths and, for each, the
success and error statuses it documents.
Read in this order
servers: the base URL. Check it matches the docs and that it is HTTPS.paths: one entry per endpoint. Count them; the count is the size of your integration.parameters: names, where they go (query, path, header), whether they are required, and their constraints. A search parameter’s description often states the search semantics, such as “the start of a company name”.components.schemas: the record shapes. Note which fields arerequired; everything else may be absent.responsesper path: every status the API documents. A company data API should document at least400,404,429and a server-side status.components.headers: response headers such asRetry-After, with their type.security: what credential, if any, each path needs.- Examples: check they are synthetic, and compare them with a live call.
What to look for in a company data API
- The ID type. Is there a schema for the company ID, with a pattern? A pattern such as a fixed prefix tells you the ID is the provider’s own, not a registry number.
- Optional fields. If
nameorstatusis not required, your code must cope without it. - The error schema. One shared schema for errors, with a code field, is what makes stable error handling possible.
- Declared security. ARES, the Czech register system, publishes an OpenAPI 3.0 document of its public REST API that declares Basic and Bearer security schemes. Read such declarations together with the prose docs before you assume a key is or is not needed.
Compare the document with the prose
Docs and OpenAPI documents drift. Pick three facts, such as the rate limit, the page size limit and one error code, and check they agree in both. Where they differ, ask the provider, and record which one you followed.
Keep it in your repository
Save the document you read next to the integration, with the date. When the provider changes it, a diff of the two versions is the fastest way to see what moved.
Questions and answers
Which OpenAPI version should a company data API publish?
Any current 3.x document is workable. CompanyRegistryAPI.com publishes an OpenAPI 3.2 document; older 3.0 documents, such as the one ARES publishes, read the same way for these purposes.
Should I generate a client from the OpenAPI document?
For a small API, a hand-written client of a few functions is often clearer. Generate one when the API has many endpoints or when you want types checked against the schema.
What if the API has no OpenAPI document?
Then the contract lives only in prose, and drift between docs and behaviour is harder to spot. Record that in your evaluation and test the error responses yourself.
Sources for this entry
- OpenAPI Specification v3.2.0
- CompanyRegistryAPI.com OpenAPI document
- CompanyRegistryAPI.com API docs
- ARES: REST API, public (OpenAPI document)
Each source supports only what its publisher says about its own product or data. Official descriptions do not establish comparative performance, and this site has run no benchmark. All sources
Continue reading
- Company data API checklist (Guide)
- OpenAPI (Definition)
- Problem details and error codes (Guide)
- Best company data API (Category guide)
- CompanyRegistryAPI.com free API (Profile)
How the related websites connect
This is one of 3 coordinated reference sites published by Coragrid. They cover neighbouring questions and feature the same product, so they are not independent endorsements of it or of each other.
Cite this entry
Best Company Data API. “Reading an OpenAPI document before you write code.” Content reviewed . https://bestcompanydataapi.com/reading-an-openapi-document