Integration & APIsAI assistants can accelerate APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. design significantly, but only if you know where they help and where they hallucinate. This lesson shows you how to use AI effectively for RESTWhat is rest?An architectural style for web APIs where URLs represent resources (nouns) and HTTP methods (GET, POST, PUT, DELETE) represent actions on those resources. and GraphQLWhat is graphql?A query language for APIs where clients specify the exact shape of data they need in a single request, avoiding over-fetching and under-fetching. API design while avoiding the common pitfalls.
What AI does well vs. poorly
| Task | AI quality | Why |
|---|---|---|
| Generating OpenAPI boilerplate | Good | Structural, well-documented pattern |
| GraphQL schema from requirements | Good | Declarative format with clear conventions |
| Naming consistency across 20+ endpoints | Poor | Loses context over long outputs |
| Pagination implementation | Mediocre | Often generates offset-only, misses cursor |
| Error response format | Poor | Different shape on each endpoint unless told |
| Business-specific validation rules | Poor | Generates generic validation, misses domain rules |
| Idempotency key handling | Poor | Almost never includes unless explicitly asked |
| DataLoader patterns for GraphQL | Good | Well-known pattern, frequently in training data |
| API versioning strategy | Mediocre | Mentions it but rarely implements consistently |
| Security headers and CORS | Good | Standard patterns, well-documented |
Prompt template 1: generating an OpenAPIWhat is openapi?A standard format for describing REST APIs - their endpoints, parameters, and response shapes. Tools can generate documentation and client libraries from it automatically. spec
Instead of saying "create an APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. for a blog," give the AI constraints:
Generate an OpenAPI 3.0 spec for a blog API with these constraints:
Resources: articles, comments, users
Naming: camelCase for JSON fields, kebab-case for URLs
Pagination: cursor-based on all list endpoints
Error format: { "error": { "code": "STRING", "message": "string", "details": [] } }
Auth: Bearer token in Authorization header
Versioning: URL prefix /v1/
Include these endpoints:
- List articles with filtering by status and author
- Get single article with embedded author
- Create article (requires auth)
- Update article (requires auth, only author or admin)
- Delete article (soft delete, requires admin)
For each endpoint, include:
- Request/response examples
- All possible error responses
- Rate limit headersThe constraints are what make the difference. Without them, the AI generates a generic CRUDWhat is crud?Create, Read, Update, Delete - the four basic operations almost every application performs on data. API. With them, it generates something close to production-ready.
Prompt template 2: designing a GraphQLWhat is graphql?A query language for APIs where clients specify the exact shape of data they need in a single request, avoiding over-fetching and under-fetching. schemaWhat is schema?A formal definition of the structure your data must follow - which fields exist, what types they have, and which are required.
Design a GraphQL schema for an e-commerce product catalog.
Requirements:
- Products have variants (size, color) with independent pricing and stock
- Categories are hierarchical (Electronics > Phones > Smartphones)
- Products can be in multiple categories
- Search with filters (price range, category, in-stock only)
Conventions:
- Use Relay-style connections for all lists (edges, nodes, pageInfo)
- Input types for all mutations
- Payload types with userErrors array for all mutations
- Use @deprecated for any fields being phased out
Include:
- Query types for product listing, search, and single product
- Mutations for creating/updating products (admin only)
- Show how variant pricing works in the schemaPrompt template 3: reviewing an existing APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. design
Review this REST API design for inconsistencies and anti-patterns:
[paste your OpenAPI spec or endpoint list]
Check for:
1. Naming consistency (casing, pluralization, URL structure)
2. Missing pagination on list endpoints
3. Inconsistent error response shapes
4. Missing idempotency support on non-safe methods
5. HTTP method misuse (POST for reads, GET with body)
6. Missing rate limiting headers
7. Versioning gaps
8. Security issues (auth on public endpoints, missing CORS)
For each issue found, show the current state and the fix.This is where AI shines, reviewing existing work for consistency. Humans get pattern-blind after staring at 40 endpoints. AI does not.
What to verify in AI-generated APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. designs
After the AI generates a spec, run through this checklist:
Naming consistency: Check every field name, every URL path, every query parameter. The AI will use createdAt in one place and created_at in another. It will use /user-profiles on one endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. and /userSettings on another.
PaginationWhat is pagination?Splitting a large set of results into smaller pages so the server and client only handle a manageable chunk at a time. on every list endpoint: Scroll through the spec and confirm every endpoint that returns an array has pagination parameters. The AI often adds pagination to /articles but forgets it on /articles/42/comments.
Error format: Copy the error response from three different endpoints and compare. Are they identical in structure? The AI often generates { "error": "string" } on one endpoint and { "message": "string", "status": 400 } on another.
Edge cases: Does the "delete" endpoint return the deleted resource or just a 204? What happens when you create a resource with a duplicate unique field? Does the spec document 409 Conflict? AI rarely handles these.
Versioning: Is /v1/ actually present on every endpoint path? AI sometimes adds it to the first few endpoints and then forgets.
/v1/articles) and then forgets it on later endpoints. Always do a final pass to verify the version prefix appears consistently on every path in the spec.The hybrid workflow
The most effective approach combines AI speed with human judgment:
- Human writes requirements: List resources, relationships, business rules, and naming conventions
- AI generates the first draft: OpenAPIWhat is openapi?A standard format for describing REST APIs - their endpoints, parameters, and response shapes. Tools can generate documentation and client libraries from it automatically. spec or GraphQLWhat is graphql?A query language for APIs where clients specify the exact shape of data they need in a single request, avoiding over-fetching and under-fetching. schemaWhat is schema?A formal definition of the structure your data must follow - which fields exist, what types they have, and which are required. with all endpoints
- Human reviews for consistency: Names, paginationWhat is pagination?Splitting a large set of results into smaller pages so the server and client only handle a manageable chunk at a time., errors, edge cases
- AI iterates on feedback: "Fix the naming to use camelCase everywhere and add cursor pagination to the comments endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users."
- Human validates the final spec: Share with frontend team for review
- AI generates implementation scaffoldingWhat is scaffolding?Auto-generating the basic file structure and starter code for a project or feature so you don't have to write it from scratch.: Route handlers, resolver stubs, TypeScript types
This workflow typically produces a production-quality APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. spec in 1-2 hours instead of 1-2 days. The AI handles the tedious boilerplateWhat is boilerplate?Repetitive, standardized code that follows a known pattern and appears in nearly every project - like setting up a server or wiring up database connections.. The human catches the subtle consistency issues that the AI misses.
The key insight: do not let the AI design your API from scratch. Give it constraints, conventions, and examples. The tighter your prompt, the less cleanup you need afterward.