Rest Api Design
Shape versioned REST endpoints with consistent pagination, error envelopes, and CRUD handlers before your agent writes Express or similar server code.
Overview
REST API Design is an agent skill for the Build phase that teaches Express-style REST endpoints with pagination, structured errors, and CRUD response shapes.
Install
npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill rest-api-designWhat is this skill?
- Express.js patterns for GET list with page/limit pagination and total counts
- Structured error payloads with machine-readable codes (NOT_FOUND, INTERNAL_ERROR)
- Single-resource GET with 404 handling and POST create with body validation
- Consistent `{ data }` success wrappers for list and detail responses
Adoption & trust: 1.4k installs on skills.sh; 250 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need a backend API but your agent keeps emitting inconsistent URLs, missing pagination metadata, or throwing unstructured error text.
Who is it for?
Solo builders implementing a first SaaS API or standardizing agent-generated Node/Express handlers.
Skip if: GraphQL-only stacks, gRPC microservices, or teams that already enforce a full OpenAPI-first codegen pipeline without REST.
When should I use this skill?
Starting or refactoring REST HTTP handlers and you want pagination, validation, and error shapes consistent across routes.
What do I get? / Deliverables
You get route handlers and JSON response patterns aligned to versioned REST conventions ready to paste into your Express (or similar) service.
- Route handler snippets
- Pagination response shape
- Standardized error JSON blocks
Recommended Skills
Journey fit
How it compares
Use for opinionated REST handler templates instead of one-off chat snippets with no shared error or pagination schema.
Common Questions / FAQ
Who is rest-api-design for?
Indie developers and small teams using AI coding agents to implement HTTP APIs for web apps, internal tools, or SaaS backends.
When should I use rest-api-design?
During Build backend work when scaffolding user lists, detail reads, creates, or when you want pagination and error JSON to match a single pattern across routes.
Is rest-api-design safe to install?
It is prompt guidance without built-in network calls; review the Security Audits panel on this Prism page before trusting any third-party skill package in your agent.
SKILL.md
READMESKILL.md - Rest Api Design
# Complete Example: Express.js ```javascript const express = require("express"); const app = express(); app.use(express.json()); // List users with pagination app.get("/api/v1/users", async (req, res) => { try { const page = parseInt(req.query.page) || 1; const limit = parseInt(req.query.limit) || 20; const offset = (page - 1) * limit; const users = await User.findAndCountAll({ limit, offset, attributes: ["id", "email", "firstName", "lastName"], }); res.json({ data: users.rows, pagination: { page, limit, total: users.count, totalPages: Math.ceil(users.count / limit), }, }); } catch (error) { res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "An error occurred while fetching users", }, }); } }); // Get single user app.get("/api/v1/users/:id", async (req, res) => { try { const user = await User.findByPk(req.params.id); if (!user) { return res.status(404).json({ error: { code: "NOT_FOUND", message: "User not found", }, }); } res.json({ data: user }); } catch (error) { res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "An error occurred", }, }); } }); // Create user app.post("/api/v1/users", async (req, res) => { try { const { email, firstName, lastName } = req.body; // Validation if (!email || !firstName || !lastName) { return res.status(400).json({ error: { code: "VALIDATION_ERROR", message: "Missing required fields", details: [ !email && { field: "email", message: "Email is required" }, !firstName && { field: "firstName", message: "First name is required", }, !lastName && { field: "lastName", message: "Last name is required", }, ].filter(Boolean), }, }); } const user = await User.create({ email, firstName, lastName }); res.status(201).location(`/api/v1/users/${user.id}`).json({ data: user }); } catch (error) { if (error.name === "SequelizeUniqueConstraintError") { return res.status(409).json({ error: { code: "CONFLICT", message: "Email already exists", }, }); } res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "An error occurred", }, }); } }); app.listen(3000); ``` # HTTP Status Codes ## HTTP Status Codes ``` Success: 200 OK - Successful GET, PATCH, DELETE 201 Created - Successful POST (resource created) 204 No Content - Successful DELETE (no response body) Client Errors: 400 Bad Request - Invalid request format/data 401 Unauthorized - Missing or invalid authentication 403 Forbidden - Authenticated but not authorized 404 Not Found - Resource doesn't exist 409 Conflict - Resource conflict (e.g., duplicate email) 422 Unprocessable - Validation errors 429 Too Many Requests - Rate limit exceeded Server Errors: 500 Internal Server Error - Generic server error 503 Service Unavailable - Temporary unavailability ``` ## API Versioning ```http # URL Path Versioning (Recommended) GET /api/v1/users GET /api/v2/users # Header Versioning GET /api/users Accept: application/vnd.myapi.v1+json # Query Parameter (Not recommended) GET /api/users?version=1 ``` ## Authentication & Security ```http # JWT Bearer Token GET /api/users Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... # API Key GET /api/users X-API-Key: your-api-key-here # Always use HTTPS in production https://api.example.com/v1/users ``` ## Rate Limiting Headers ```http HTTP/1.1 200 OK X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 995 X-RateLimit-Reset: 1642262400 ``` # OpenAPI Documentation ## OpenA