- Home
- Skills
- APIs & Backend
- REST API Design: APIs Developers Love
Works with the AI Agents you already use
REST API Design: APIs Developers Love
Design or review REST APIs: naming, methods and status codes, RFC 9457 errors, cursor pagination, filtering, idempotency keys, ETags, versioning, auth, rate limits, webhooks and a complete OpenAPI 3.1 spec with examples.
Free
REST API Design: APIs Developers Love
Example session with this skill installed
Design a new set of endpoints for an e-commerce order management system. I need to handle order creation, status updates, and listing orders for a customer with pagination.
- Read your context and instructions
- Compiled the rest api design
I have mapped out the order management resources. The design follows plural noun conventions, uses RFC 9457 for errors, and includes idempotency for order placement.
Order Management API Design
| Method | Path | Purpose | Auth | Success | Errors |
|---|---|---|---|---|---|
| POST | /orders | Place a new order | orders:write | 201 | 400, 401, 409 |
| GET | /customers/{id}/orders | List customer orders | orders:read | 200 | 401, 404 |
| GET | /orders/{id} | Get order details | orders:read | 200 | 401, 404 |
| PATCH | /orders/{id} | Partial update (e.g. status) | orders:write | 200 | 400, 401, 404, 412 |
| POST | /orders/{id}:cancel | Cancel an order | orders:write | 200 | 401, 404, 409 |
openapi: 3.1.0
info:
title: Order Management API
version: 1.0.0
paths:
/orders:
post:
summary: Place order
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInput'
responses:
'201':
description: Created
headers:
Location:
schema:
type: string
'400':
$ref: '#/components/responses/Error'
components:
schemas:
OrderInput:
type: object
properties:
customerId:
type: string
items:
type: array
items:
$ref: '#/components/schemas/LineItem'
LineItem:
type: object
properties:
productId:
type: string
quantity:
type: integer
responses:
Error:
content:
application/problem+json:
schema:
type: object
properties:
type: { type: string }
title: { type: string }
status: { type: integer }
detail: { type: string }
Next steps
- Implement the
Idempotency-Keystorage logic with a 24-hour TTL. - Configure your API gateway to validate the
orders:writescope for POST/PATCH operations. - Define the HMAC signing secret for the
order.createdwebhook notification.
Connects securely to your tools. The creator never sees your data.
About this skill
Building APIs that developers actually enjoy using is harder than it looks. Inconsistent naming, vague error codes, and poor pagination logic lead to integration friction and support tickets. This skill enforces strict REST conventions to ensure your API is predictable, scalable, and standards-compliant.
What it does
- Standardizes resource naming using plural nouns and consistent casing across all endpoints.
- Enforces HTTP semantics by mapping actions to correct methods like PUT for idempotency and PATCH for partial updates.
- Implements RFC 9457 errors to provide machine-readable, consistent error responses for all failure states.
- Architects scalable patterns including cursor-based pagination, ETag-based concurrency control, and idempotency keys.
- Generates OpenAPI 3.1 specs complete with schemas, real-world examples, and security definitions.
How it works
- Analyze requirements by mapping out resources, relationships, and specific business use cases.
- Draft design starting with an endpoints table covering paths, methods, and expected status codes.
- Generate documentation in OpenAPI 3.1 YAML format including detailed request/response objects.
- Audit and refine against a comprehensive checklist to catch breaking changes or security gaps like IDOR.
Frameworks & tools
This skill produces standard OpenAPI 3.1 YAML compatible with Swagger UI, Redoc, and Postman. It follows industry standards like RFC 9457 for errors, ISO 8601 for time, and OAuth2/OIDC for authentication patterns.
Why this beats prompting it yourself
Most LLMs mix different API styles or forget edge cases like 412 Precondition Failed for concurrency. This skill applies a rigid architectural framework that guarantees consistency in error handling, pagination, and idempotency across your entire service.
Use cases
- Design a new microservice API from scratch with full OpenAPI documentation.
- Review existing endpoints to identify non-standard status codes or naming.
- Add complex features like cursor pagination or HMAC-signed webhooks to an existing spec.
- Refactor a legacy API to follow modern REST best practices and RFC 9457.
Known limitations
Does not support SOAP or gRPC. Focuses on REST/HTTP patterns only. Requires manual implementation of the generated logic in your specific backend language.
Focuses strictly on REST/HTTP; no support for SOAP or gRPC. Does not generate server-side implementation code, only specifications and design documentation.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
This skill has been used 7 times.
Trust & safety
Security scan
Security scan passed 7 days ago
- Free with an Agensi account