Api Design

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass, no license.

Audit 0.4.1 · source sha dd4da722e22a · 18 Oct 2026Report an issue or request a re-scan

• Publisheragulli GitHub userOwner of the repository this skill is read from
• Source folderagulli/atlas-agents/ch09_agent_skills/skills/api-designThe exact folder we audited
• LicenceNot declaredAs the repository states it
• Commit pinned for this verdictdd4da722e22aA new audit runs when the source changes
• Repository statusNot archivedLast push 93 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Design or review REST and GraphQL API interfaces. Use when asked to design an API, review endpoint structure, define request/response schemas, or improve API ergonomics.

---
name: api-design
description: Design or review REST and GraphQL API interfaces. Use when asked to design an API, review endpoint structure, define request/response schemas, or improve API ergonomics.
license: MIT
---

## Overview

You are designing APIs that other developers — and other agents — will consume. Clarity and predictability matter more than cleverness.

## Process

1. **Identify the domain objects.** List every noun the API needs to represent. Group them by relationship.
2. **Design the resource hierarchy.** Use plural nouns for collections: `/users`, `/users/{id}/orders`. Never use verbs in URLs — the HTTP method IS the verb.
3. **Define schemas.** Write request and response schemas as JSON examples. Every field must have:
   - A type
   - Whether it's required or optional
   - An example value
   - Validation constraints (min/max length, regex pattern, allowed values)
4. **Error contract.** Define a consistent error envelope:
   ```json
   {"error": {"code": "VALIDATION_FAILED", "message": "...", "details": [...]}}
   ```
   Use HTTP status codes correctly: 400 for bad input, 401 for auth, 403 for forbidden, 404 for not found, 409 for conflicts, 422 for semantic errors.
5. **Pagination.** All list endpoints must support cursor-based pagination by default. Offset pagination is acceptable only if explicitly requested.
6. **Versioning.** Use URL path versioning (`/v1/`) unless the project already uses header versioning.

## Rationalizations

| Excuse | Rebuttal |
|--------|----------|
| "We can add pagination later" | No. Adding pagination to an existing endpoint is a breaking change. Design it in from day one. |
| "Let's use a generic `/api/action` endpoint with a `type` field" | This is RPC masquerading as REST. Use proper resource URLs. |
| "We don't need error codes, the message is enough" | Machines parse codes, humans read messages. You need both. |

## Verification

- [ ] Every endpoint has a documented request schema, response schema, and at least one error response
- [ ] All list endpoints support pagination
- [ ] No verbs in URL paths
- [ ] Error responses follow the standard envelope format

Excerpt, first 2,153 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-18
   ✓SAFE B 89 / 100

   first audit · source dd4da722e22a

Questions about Api Design

• github.com/agulli/atlas-agents/tree/main/ch09_agent_skills/skill — the audited source at commit dd4da722e22a and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology