# Design Clean REST and GraphQL APIs

Designing consistent APIs from scratch is slow and error-prone, and inconsistent endpoints confuse consumers. This skill gives Claude a structured workflow with proven patterns for endpoints, errors, versioning, authentication, and OpenAPI documentation.

## Install

```bash
npx skillstore add cloudai-x/designing-apis
```

## Metadata

- Status: approved
- Slug: cloudai-x-designing-apis
- Skillstore revision: r2
- Version status: missing
- Tree hash: af8e2e8e0b525774a293fdde36ce86b2744013932f8fd3399963017945293984
- Author: CloudAI-X
- GitHub username: CloudAI-X
- License: MIT
- Repository: https://github.com/CloudAI-X/claude-workflow/tree/main/skills/designing-apis
- Ref: c68df504887c54bf71d2d467a1fbebde49467868
- 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: network, external\_commands
- Quality score: 79
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/cloudai-x-designing-apis
- Manifest: https://skillstore.pages.dev/api/skills/cloudai-x-designing-apis/manifest

## Capabilities

- Designs resource-based REST endpoints using nouns and correct HTTP methods
- Recommends appropriate HTTP status codes for each operation and error case
- Defines consistent success, list-pagination, and error response formats
- Advises on URL and header versioning strategies for APIs
- Documents authentication patterns such as JWT bearer tokens and API keys
- Produces OpenAPI 3.0 specification templates from a provided starting point

## Use Cases

- Design a new REST API from scratch: A backend developer uses the skill to structure endpoints, pick status codes, and define request and response formats for a new service.
- Review an existing API contract: A tech lead asks the skill to check an API against the validation checklist for consistency, correct methods, and pagination.
- Write an OpenAPI specification: An API documentation writer uses the OpenAPI template to produce a complete and valid specification for stakeholders.

## Prompt Templates

### Design endpoints for a resource

```
Design REST endpoints for managing a 'products' resource. Include list, get, create, update, and delete operations with the correct HTTP methods and status codes.
```

### Define response formats

```
Define consistent JSON success, paginated list, and error response formats for my user management API.
```

### Plan versioning and authentication

```
Recommend a versioning strategy and an authentication pattern for a public API that will have external consumers.
```

### Produce an OpenAPI specification

```
Create a complete OpenAPI 3.0 specification for an orders API with endpoints for listing, creating, and retrieving orders, including request bodies, responses, and schemas.
```

## Limitations

- Provides design guidance and documentation only; it does not implement or run API code
- Does not test, deploy, or validate a live API against a running server
- Covers REST and GraphQL patterns but not every protocol such as gRPC or SOAP
- Security advice is general guidance and does not replace a full security review

## Best Practices

- Use resource-based URLs with nouns and match HTTP methods to operations.
- Keep response formats consistent across every endpoint, including errors.
- Document the design with a complete OpenAPI specification before implementation.

## Anti Patterns

- Do not put verbs in URLs, such as /getUser or /createUser.
- Do not return the same 200 status code for every response regardless of outcome.
- Do not place sensitive data such as tokens or passwords in URLs or query strings.

## Security Audit

- Audited at: 2026-07-18T10:52:57.506\+00:00
- Summary: This skill is a static Markdown reference guide for designing REST and GraphQL APIs. All 36 static findings are false positives: the flagged patterns are Markdown code fences misread as shell/Ruby backtick execution, an example placeholder URL, and REST/OpenAPI documentation snippets misread as system reconnaissance. There is no executable code, no network activity, no filesystem or environment access, and no prompt-injection content. The skill is safe.

## Stats

- Views: 212
- Downloads: 8
- Favorites: 0
- Popularity score: 0