Api design

Skill 0xc000022070/agentic-flake/examples/3-home-manager/skills/api-design

Composable agent skills and project-scoped environments for Nix.

Install

npx -y skills add 0xc000022070/agentic-flake --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

REST API design patterns and conventions

SKILL.md

2.9 KB, as published. Nobody here has run it

API Design Patterns

Guidelines for designing REST APIs.

Resource-Oriented Design

Design around resources, not actions.

Good

GET /users/123 — Get a user
POST /users — Create a user
PUT /users/123 — Update a user
DELETE /users/123 — Delete a user

Avoid

GET /getUser — Action-oriented
POST /createNewUser — Redundant with HTTP method

HTTP Methods

Method	Purpose	Idempotent
GET	Retrieve	Yes
POST	Create	No
PUT	Full update	Yes
PATCH	Partial update	No
DELETE	Delete	Yes

Status Codes

2xx Success

200 OK — Request succeeded
201 Created — Resource created (include Location header)
204 No Content — Success, no response body

4xx Client Error

400 Bad Request — Invalid input
401 Unauthorized — Authentication required
403 Forbidden — Authenticated, not allowed
404 Not Found — Resource doesn't exist
422 Unprocessable Entity — Valid format, semantic error

5xx Server Error

500 Internal Server Error — Unexpected error
503 Service Unavailable — Temporarily down

Error Responses

Consistent error format:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "User email is required",
    "details": {
      "field": "email"
    }
  }
}

Request/Response Bodies

JSON Structure

Use camelCase for fields
Flat structure (max 2-3 nesting levels)
Avoid redundant wrappers

{
  "userId": 123,
  "name": "Alice",
  "email": "[email protected]",
  "createdAt": "2026-01-15T10:30:00Z"
}

Timestamps

Use ISO 8601: 2026-01-15T10:30:00Z
Timezone-aware (UTC)

Pagination

GET /users?page=1&limit=20

Response:

{
  "data": [{...}, {...}],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "hasMore": true
  }
}

Filtering, Sorting

Filtering

GET /users?role=admin&status=active

Sorting

GET /posts?sort=createdAt:desc,title:asc

Versioning

URL Path (Recommended)

GET /v1/users
GET /v2/users

Header

Accept: application/vnd.myapi.v1+json

Announce 12 months before deprecating old versions.

Authentication

Bearer Token

Authorization: Bearer <token>

API Key

X-API-Key: your-key-here

Rate Limiting

Include in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 500
X-RateLimit-Reset: 1234567890

Common Patterns

Nested Resources

GET /organizations/org1/teams/team1/members

Or flatten with query params:

GET /members?organizationId=org1&teamId=team1

Batch Operations

POST /users/batch
{
  "operations": [
    {"op": "create", "data": {...}},
    {"op": "update", "id": "123", "data": {...}}
  ]
}