The API Design Conversation

You're building an API that other developers will use. Should it be REST? GraphQL? gRPC? Should you version it? How do you handle errors? How do you evolve it without breaking clients? How do you make it consistent across endpoints? When do you deprecate endpoints?

These decisions get baked into your codebase. Change them later and you're breaking changes or maintaining multiple versions indefinitely. Get them wrong initially and developers hate using your API, they complain, you get a reputation for bad DX. One year later, 30% of your support tickets are "why is your API so hard to use?"

This is where AI becomes a valuable design partner. Not as a source of truth, but as someone who's seen thousands of APIs and can help you think through your design systematically. AI can catch gaps in your thinking, suggest edge cases, and propose consistent patterns before you've built it.

What AI is Good At

• Suggesting consistent API structures
  - Identifying what you might have missed (error handling, rate limiting, pagination)
  - Evaluating trade-offs between REST and other approaches
  - Generating OpenAPI/Swagger specs
  - Catching inconsistencies in endpoint naming
  - Suggesting versioning strategies
  - Thinking through edge cases

What it's not good at:

• Understanding your specific client requirements
  - Knowing whether you should be building an API at all
  - Deciding between REST and GraphQL (depends on your clients)
  - Making architectural trade-offs

You understand your problem. The AI helps you design a good solution.

The API Design Framework: Describe what you're building and who'll use it. The AI suggests a design. You evaluate it. Iterate.

Designing Your API

Step 1: Define Your Resources and Operations

"I'm building a project management API. Resources:
- Projects (create, read, update, delete, list)
- Tasks (create, read, update, delete, list, assign to users)
- Users (create, read, update, delete, list)
- Comments on tasks (create, read, delete)

Operations:
- List projects with filtering and pagination
- Get a project with all its tasks
- Mark a task as complete
- Update task status
- Get tasks assigned to me
- Add a comment to a task"

Step 2: Ask for an API Design

"Design a RESTful API for this. Include:
- Endpoint structure
- Request/response formats
- Error handling
- Pagination strategy
- Rate limiting
- Authentication

Explain the trade-offs in your design."

Step 3: Evaluate the Design

The AI suggests endpoints like:

GET /projects - list projects
GET /projects/:id - get a project
POST /projects - create a project
PUT /projects/:id - update a project
DELETE /projects/:id - delete a project
GET /projects/:id/tasks - get tasks in a project
GET /tasks/assigned-to-me - get my tasks
POST /tasks/:id/comments - add a comment

Review for consistency, completeness, and whether it matches how clients will use it.

Step 4: Address Details

Dig into specific concerns:

"For pagination, should I use limit/offset or cursor-based? Our datasets are up to 10K items. What's the trade-off?"

AI explains: "Limit/offset is simpler to implement but inefficient with large offsets (database has to scan rows it doesn't return). Cursor-based is harder to implement but scales better. For 10K items, limit/offset is fine. Cursor-based only matters at millions of items."

Another concern: "If a user creates a task, should they automatically be assigned as the owner? Or do we require explicit assignment?"

AI suggests: "Implicit assignment reduces steps for common case. But always allow explicit assignment. Default behavior should be: creator is owner, but they can assign to someone else immediately."

API Specification and Documentation

Once you've designed your API, generate the spec. This is where you move from concept to concrete.

Pattern 1: OpenAPI Specification

"Generate an OpenAPI 3.0 spec for this API:

Endpoints:
[paste your endpoint list]

Request/Response formats:
[describe what data flows]

Error codes:
- 400: Invalid input
- 401: Unauthorized
- 404: Not found
- 429: Rate limited
- 500: Server error

Include example requests and responses for each endpoint."

The AI generates a complete OpenAPI spec. You review for accuracy, add any missing details, and use it to auto-generate docs and SDKs.

Pattern 2: API Guidelines Document

"Create API design guidelines for our team. Include:
- Naming conventions (resources, endpoints, parameters)
- Error response format
- Success response format
- Pagination approach
- Rate limiting strategy
- Versioning approach
- Authentication method
- Common patterns for filtering and searching

Document this so the next API we build follows the same conventions."

The AI creates a reference document. Your team uses it for consistency.

Evolution and Versioning

APIs change. You need a strategy for evolution without breaking clients. This is where most API designs fail long-term.

Non-Breaking Changes

Ask the AI: "Which of these changes are safe without versioning?
1. Adding a new optional parameter to an endpoint
2. Adding a new field to a response
3. Renaming an existing parameter
4. Changing the response format
5. Adding rate limiting where there was none"

AI's response: "1 and 2 are safe (new optional params, new response fields don't break existing clients). 3, 4, 5 are breaking. You need a versioning strategy."

Versioning Strategy

"Should I version by URL (/v1/projects, /v2/projects) or by header? What's the trade-off?"

AI: "URL versioning is easier for clients and simpler to manage. Header versioning is cleaner but less obvious. For external APIs, URL versioning is more common. Choose one and stick with it."

Deprecation

"I want to deprecate an endpoint. How should I handle this?"

AI suggests: "1. Mark it as deprecated in docs and responses (Deprecation header). 2. Give clients at least 6-12 months notice. 3. Monitor usage. 4. Remove only after usage drops below a threshold. 5. Provide clear migration path to new endpoint."

Real API Design Example

Scenario: You're building a payment processing API. Three types of operations: creating payments, checking status, handling refunds.

Your initial thought: POST /payments, GET /payments/:id, POST /payments/:id/refunds

Ask the AI: "Here's my payment API design. What am I missing? What edge cases? What could frustrate developers using this?"

AI response: "Good start. I see some concerns:
1. Idempotency: if a request fails and retries, you'll create duplicate payments. Add an idempotency-key header. This is critical for payment systems.
2. Webhooks: clients need to know when a payment settles or fails asynchronously. Add webhook registration endpoints.
3. Error details: payment failures have different causes (insufficient funds, expired card, rate limit exceeded). Your error responses should differentiate so clients can handle them correctly.
4. Batch operations: clients might create many payments. Add a batch endpoint.
5. Search/filtering: clients need to query payment history with filters (date range, status, amount range).
6. Pagination: results can be large. How do clients get page 2?
7. Rate limiting: how will you rate limit? Tell clients in response headers how many requests they have left.
8. Timeouts: how long should a request wait? Set expectations in docs.
9. Retry behavior: which errors are retriable? Which are permanent?"

This catches things you'd discover months later in production, and then spend weeks debugging client integrations.

Case Study: Fintech API Design

A fintech company built a payments API following this process. They asked AI for gaps. One suggestion: "What happens if a webhook delivery fails? Do you retry? How many times?" They hadn't thought about it. They implemented exponential backoff with 24-hour max retry window. Six months in production, a payment processor API went down for 4 hours. Their webhooks continued retrying every hour. When the processor came back up, 50,000 webhooks were queued and delivered within minutes. Clients knew payment status was inconsistent for 4 hours, but they didn't lose data or money. That webhook design, suggested by AI during review, prevented a disaster.

Key Insight

A good API feels natural to use, handles edge cases gracefully, and evolves without breaking things. AI helps you think through these dimensions systematically instead of discovering issues after launch.

SDK Generation

Once your API is designed and spec'd, you can auto-generate SDKs from your OpenAPI spec. This saves weeks of SDK development.

"Generate Python and Node.js SDKs from this OpenAPI spec:
[paste spec]

The SDKs should:
- Handle authentication
- Include retry logic with exponential backoff
- Support timeout configuration
- Include type hints (Python) or TypeScript
- Include example usage for each endpoint"

The AI generates SDKs that clients can use immediately. You review for correctness, test, and publish. Save 4-6 weeks of engineering effort per language. A company with 5 language SDKs saves 20-30 weeks of engineering time.

What to Do Monday Morning

• For an API you're about to build, describe the resources and operations to the AI. Ask for a complete design. Review it for completeness. See if you'd do it differently. Ask follow-up questions on edge cases.
  - Take an existing API you built. Ask the AI: "What am I missing? What edge cases did I not handle? What would make this harder for clients to use? What didn't I think about?"
  - Create API design guidelines for your team. Have the AI help structure them based on your existing APIs. Use for all future APIs to maintain consistency.
  - Generate an OpenAPI spec for your most important API. Use it to auto-generate documentation and SDKs. Update as your API evolves.
  - Document deprecation strategy. Write down how you'll handle API evolution, versioning, and deprecation. This prevents costly mistakes later.

FAQ

Q: REST vs. GraphQL, which should I choose?

A: Ask your clients. REST is simpler and works well for most use cases. GraphQL is better when clients have very different data needs (web vs. mobile vs. third-party integrations). Don't choose based on hype. Choose based on your clients' actual requirements.

Q: How do I know if my API design is good?

A: If developers can use it without reading docs for every endpoint. If error messages are clear. If the design is consistent across endpoints. If you can evolve it without breaking clients. Ask the AI to review against these criteria.

Q: Should I version my API?

A: Almost certainly yes, eventually. Start unversioned if you're early. Move to versioning when you need to make breaking changes. Don't version prematurely. It's complexity you don't yet need.

Q: How long should I support an old API version?

A: Give clients 12-18 months notice before deprecation. Monitor usage. Remove only after usage is very low (less than 5% of requests). The cost of supporting it is usually lower than the pain of forced migrations.

Q: How do I test my API design before implementing?

A: Generate mock responses from your OpenAPI spec. Let clients test against mocks before you implement. This catches design issues early. Much cheaper than discovering them after implementation.

On This Page

Watch the Lecture
The API Design Conversation
Designing Your API
API Specification and Documentation
Evolution and Versioning
Real API Design Example
SDK Generation
What to Do Monday Morning
FAQ

Chapter Details

Part of