# Design Consistent REST APIs

Inconsistent endpoints make APIs difficult to learn and maintain. This skill provides practical conventions for routes, methods, responses, errors, pagination, and documentation.

## Install

```bash
npx skillstore add benny9193/api-design
```

## Metadata

- Status: approved
- Slug: benny9193-api-design
- Skillstore revision: r2
- Version status: missing
- Tree hash: eba38a527ba2bd61234f833eb642e83e9bcf5c1af9b042e5820c0e96470ff0b3
- Author: Benny9193
- GitHub username: Benny9193
- License: MIT
- Repository: https://github.com/Benny9193/devflow/tree/master/skills/api-design
- Ref: 8c3e20bba512c392d9b02ee748b18e0b09d4982c
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands, env\_access
- Quality score: 78
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/benny9193-api-design
- Manifest: https://skillstore.pages.dev/api/skills/benny9193-api-design/manifest

## Capabilities

- Recommends noun-based, plural resource paths with limited nesting.
- Maps common resource operations to appropriate HTTP methods and status codes.
- Defines consistent success, collection, validation, and error response structures.
- Explains offset and cursor pagination, filtering, sorting, and field selection.
- Provides guidance for versioning, authentication, rate limits, and OpenAPI documentation.
- Supplies a checklist for reviewing REST API consistency.

## Use Cases

- Plan a new service API: Create a consistent endpoint plan before backend implementation begins.
- Review an existing API: Identify inconsistent routes, methods, status codes, pagination, and response formats.
- Define a shared API standard: Turn practical REST conventions into team documentation and review criteria.

## Prompt Templates

### Design basic endpoints

```
Design REST endpoints for [resource]. Include list, create, retrieve, update, and delete operations with suitable status codes.
```

### Standardize responses

```
Propose consistent success, collection, validation, and error responses for [service]. Explain each field in plain language.
```

### Review an API specification

```
Review this API specification for route naming, HTTP methods, status codes, pagination, filtering, versioning, authentication, and errors: [specification].
```

### Design a scalable contract

```
Design a versioned REST contract for [domain]. Include relationships, cursor pagination, filtering, rate limits, authentication, error conventions, and OpenAPI documentation requirements.
```

## Limitations

- The skill provides design guidance but does not generate production server code.
- Examples are generic and require adaptation to domain rules and framework conventions.
- Security topics are introductory and do not replace a threat model or security review.
- The guidance focuses on REST APIs and does not cover GraphQL or event-driven contracts.

## Best Practices

- Define shared naming, response, and error conventions before adding endpoints.
- Document every request, response, status code, and failure case.
- Review security, authorization, and data exposure separately from interface consistency.

## Anti Patterns

- Do not place action verbs in resource URLs when HTTP methods already express the action.
- Do not return one status code for every success and failure.
- Do not expose unbounded collections without pagination and rate limits.

## Security Audit

- Audited at: 2026-07-23T11:15:24.548\+00:00
- Summary: All 48 static findings are false positives caused by Markdown fences, API examples, and ordinary terminology. The skill contains no executable commands, environment access, prompt injection, or malicious intent.

## Stats

- Views: 259
- Downloads: 10
- Favorites: 0
- Popularity score: 0