A developer portal is more than a place to dump your API docs. Done well, it's the difference between a developer who gives up after 20 minutes and one who builds something real with your API and tells their team about it.
This guide covers what to include, how to structure it, and the details that separate a forgettable portal from one developers actually bookmark — using the PetStore API ecosystem as a reference throughout.
A developer portal is the front door to your API. It's where developers go to:
The PetStore API's demo portal at petstore3.swagger.io is a minimal example — it shows the API reference and lets you make live calls. A production developer portal goes much further.
The first page a developer sees should answer three questions in under 10 seconds:
## PetStore API
Manage pet store inventory, process orders, and handle user accounts
through a simple REST API.
- 15 endpoints covering pets, orders, and users
- JSON responses, OAuth2 and API key auth
- Free tier: 1,000 requests/day
[Get API Key →] [View Docs →] [Try in Sandbox →]
No marketing fluff. Just the facts and a clear path forward.
The getting started guide is the most important page in your portal. It should take a developer from zero to their first successful API call in under 5 minutes.
Structure it as a numbered walkthrough:
Step 1: Get your API key
Sign up at petstore.example.com/signup. Your API key will be emailed
to you immediately. It looks like this:
api_key: abc123def456ghi789
Step 2: Make your first request
Show the simplest possible working example:
curl -X GET "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available" \
-H "Accept: application/json" \
-H "api_key: your-api-key-here"
Expected response:
[
{
"id": 1,
"name": "Buddy",
"status": "available",
"photoUrls": ["https://example.com/buddy.jpg"]
}
]
Step 3: Create a pet
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
-H "Content-Type: application/json" \
-H "api_key: your-api-key-here" \
-d '{
"name": "Max",
"photoUrls": ["https://example.com/max.jpg"],
"status": "available"
}'
Each step should be copy-pasteable and produce a visible result. Developers need to feel momentum early.
The reference docs are where developers spend most of their time. Every endpoint needs:
GET /pet/{petId}Here's what a well-documented endpoint looks like in OpenAPI format:
/pet/{petId}:
get:
summary: Find pet by ID
description: |
Returns a single pet. Use this endpoint when you have a specific
pet ID and need its full details including photos and tags.
operationId: getPetById
tags:
- pet
parameters:
- name: petId
in: path
required: true
description: Numeric ID of the pet to retrieve
schema:
type: integer
format: int64
minimum: 1
example: 10
responses:
'200':
description: Pet found successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
example:
id: 10
name: "Max"
status: "available"
photoUrls:
- "https://example.com/max.jpg"
'400':
description: Invalid ID format (must be a positive integer)
'404':
description: No pet found with this ID
'401':
description: Missing or invalid API key
The example field in the response schema is what shows up in Swagger UI and Redoc — make it realistic, not string or 123.
Developers want to work in their language. Provide code samples for every major language, and consider publishing official SDKs for the most popular ones.
Minimum code sample coverage:
Python SDK example for PetStore:
# pip install petstore-sdk
from petstore import PetStoreClient, Pet
client = PetStoreClient(api_key="your-api-key")
# List available pets
pets = client.pets.list(status="available")
for pet in pets:
print(f"{pet.name} - {pet.status}")
# Create a new pet
new_pet = client.pets.create(Pet(
name="Luna",
photo_urls=["https://example.com/luna.jpg"],
status="available"
))
print(f"Created pet with ID: {new_pet.id}")
# Update pet status
client.pets.update_status(new_pet.id, "pending")
An SDK removes friction. Developers don't have to think about HTTP methods, headers, or JSON serialization — they just call methods.
If you don't have official SDKs, at minimum provide a Postman collection and an OpenAPI spec that developers can use to generate their own clients.
A sandbox is a safe place to experiment without affecting real data or incurring costs. It's one of the highest-value things you can add to a developer portal.
What a good sandbox provides:
https://sandbox.petstore.example.com/api/v3Document the sandbox clearly:
## Sandbox Environment
Use the sandbox to test your integration without affecting production data.
Base URL: https://sandbox.petstore.example.com/api/v3
The sandbox is pre-populated with:
- 50 pets in various statuses
- 10 test orders
- 5 test user accounts
Test API key: sandbox_key_abc123
Note: Sandbox data resets every 24 hours at midnight UTC.
Pre-built test scenarios are a nice touch:
## Test Scenarios
| Scenario | Pet ID | Expected Behavior |
|----------|--------|-------------------|
| Available pet | 1 | Returns pet with status "available" |
| Sold pet | 2 | Returns pet with status "sold" |
| Pet not found | 99999 | Returns 404 |
| Invalid ID | abc | Returns 400 |
This lets developers test error handling without having to engineer failure conditions themselves.
An API explorer lets developers make real API calls directly from the browser, without writing any code. It's the fastest way to understand what an endpoint does.
Swagger UI is the most common choice — it renders directly from your OpenAPI spec:
<!DOCTYPE html>
<html>
<head>
<title>PetStore API Explorer</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
SwaggerUIBundle({
url: "https://petstore3.swagger.io/api/v3/openapi.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "StandaloneLayout",
// Pre-fill the API key field
onComplete: () => {
ui.preauthorizeApiKey("api_key", "sandbox_key_abc123");
}
});
</script>
</body>
</html>
Pre-filling the sandbox API key removes one more step for developers trying things out.
Redoc is worth considering as an alternative — it has a cleaner three-panel layout that's easier to navigate for large APIs, though it doesn't support the "Try it out" functionality by default.
Authentication is where most developers get stuck first. Give it its own dedicated page.
## Authentication
The PetStore API supports two authentication methods:
### API Key (Recommended for getting started)
Pass your API key in the `api_key` request header:
```bash
curl -H "api_key: your-api-key" https://petstore3.swagger.io/api/v3/pet/1
API keys are tied to your account and have the same permissions as your user.
OAuth2 is required for operations that access user data.
Available scopes:
| Scope | Description |
|---|---|
read:pets |
Read pet data |
write:pets |
Create and modify pets |
read:orders |
Read order data |
write:orders |
Create and modify orders |
Getting a token:
curl -X POST "https://petstore3.swagger.io/oauth/token" \
-d "grant_type=client_credentials" \
-d "client_id=your-client-id" \
-d "client_secret=your-client-secret" \
-d "scope=read:pets write:pets"
Tokens expire after 3600 seconds. Use the refresh_token to get a new one.
---
### 8. Changelog and Migration Guides
Developers need to know when things change. A changelog is a trust signal — it shows you take backward compatibility seriously.
```markdown
## Changelog
### v3.1.0 — March 2024
**New features:**
- Added `GET /pet/search` endpoint with full-text search support
- Added `embed` query parameter to include related resources
**Improvements:**
- Improved error messages for invalid pet IDs
- Added `requestId` field to all error responses
---
### v3.0.0 — January 2024 (Breaking Changes)
**Breaking changes:**
- `photoUrls` is now required when creating a pet (was optional in v2)
- `status` field now only accepts: `available`, `pending`, `sold`
(previously accepted any string)
**Migration guide:** See [Migrating from v2 to v3](/docs/migration/v2-to-v3)
---
### v2.1.0 — September 2023
**New features:**
- Added bulk pet creation: `POST /pet/bulk`
- Added `GET /store/inventory/summary` endpoint
For breaking changes, always link to a migration guide. The migration guide should show before/after code examples for every breaking change.
A dedicated error reference page saves developers hours of debugging time.
## Error Reference
### HTTP Status Codes
| Code | Meaning | Common Causes |
|------|---------|---------------|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid parameters or request body |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | Valid credentials but insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 405 | Method Not Allowed | Wrong HTTP method for this endpoint |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Something went wrong on our end |
### Error Codes
| Code | Description | How to Fix |
|------|-------------|------------|
| `INVALID_PET_ID` | Pet ID must be a positive integer | Check that the ID is numeric |
| `PET_NOT_FOUND` | No pet with this ID exists | Verify the ID or check if it was deleted |
| `INVALID_STATUS` | Status must be available, pending, or sold | Use one of the three valid values |
| `RATE_LIMIT_EXCEEDED` | Too many requests | Wait for the reset time in the response headers |
Developers get stuck. Give them places to get help.
What to include:
Response time expectations matter:
## Getting Help
- **Community forum:** Usually answered within 24 hours by the community
- **GitHub issues:** Triaged within 2 business days
- **Email support:** Response within 1 business day (paid plans)
- **Status page:** status.petstore.example.com
Setting expectations prevents frustration. Developers can plan around a 24-hour response time; they can't plan around "we'll get back to you."
Here's a navigation structure that covers all the bases without overwhelming developers:
Developer Portal
├── Home (landing page)
├── Getting Started
│ ├── Quick Start (5-minute guide)
│ ├── Authentication
│ └── Making Your First Request
├── Guides
│ ├── Managing Pets
│ ├── Processing Orders
│ ├── User Management
│ └── Webhooks
├── API Reference
│ ├── Pets
│ ├── Store
│ └── Users
├── API Explorer (Swagger UI)
├── SDKs & Libraries
│ ├── Python
│ ├── JavaScript
│ ├── Go
│ └── Java
├── Sandbox
├── Changelog
├── Migration Guides
├── Error Reference
└── Support
├── Community Forum
├── GitHub
└── Status Page
The key is progressive disclosure — developers can get started without reading everything, but everything they need is there when they need it.
A developer portal is a product. Measure it like one.
Metrics worth tracking:
If developers are consistently asking the same question in your forum, that's a documentation gap. Fill it.
A great developer portal isn't built in a day. Start with the essentials — a clear landing page, a working getting started guide, complete API reference, and a sandbox — then layer in the rest based on what your developers actually need.
The PetStore API is a useful reference point because it demonstrates the core patterns cleanly. But the best developer portals go further: they anticipate questions, provide working code in multiple languages, and make it genuinely easy to go from curious to productive.
That's the goal. Not just documentation — a portal that turns developers into advocates.
