Every public API comes with documentation. But some APIs go further — they ship an OpenAPI spec. It's a single JSON file that describes every endpoint, every parameter, and every possible response. Read it once and you know exactly how to use the API before writing a single line of code.
Let's do that right now.
What Is an OpenAPI Spec?
It's a standardized JSON (or YAML) file that describes an API completely. Endpoints, required parameters, response shapes — all in one place. Tools like Swagger UI turn it into interactive documentation, but the raw file is what matters here.
Step 1 — Get the Spec
We're using the Swagger Petstore. It's a fake pet store API built purely for learning. Open this in your browser:
https://petstore3.swagger.io/api/v3/openapi.json
Save it locally. Don't try to memorize anything — just scan the structure. You'll notice three things that matter:
paths — all available endpoints
parameters — what each endpoint accepts
responses — what comes back
That's the whole mental model.
Step 2 — Find Your Endpoint
Search for /pet/findByStatus in the spec. Here's what it looks like:
json"/pet/findByStatus": {
"get": {
"summary": "Finds Pets by status",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": ["available", "pending", "sold"]
}
}
]
}
}
The spec tells you everything. One query parameter called status, three allowed values. No guessing.
Step 3 — Call It in Python
pythonimport requests
response = requests.get(
"https://petstore3.swagger.io/api/v3/pet/findByStatus",
params={"status": "available"}
)
data = response.json()
print(f"Status: {response.status_code}")
print(f"Pets returned: {len(data)}")
print(data[0]) # peek at the first result
Run it. Then try swapping available for pending or sold and see what changes.
Step 4 — Read the Response
You'll get back a list of pet objects. Something like:
json{
"id": 1,
"name": "doggie",
"status": "available",
"photoUrls": []
}
The spec told you this was coming — check the responses section for /pet/findByStatus. It describes the exact shape of what you just received.
Why This Actually Matters
Most developers go straight to tutorial blog posts when they want to use an API. The spec is better. It's always up to date, it's authoritative, and it tells you things blog posts skip — like which parameters are optional, what the valid enum values are, and what error responses look like.
Get comfortable reading specs now. As your projects grow more complex, this habit saves hours.
Top comments (0)