Skills api-design-principles
🧭
api-design-principles
Safe 🌐
Network access⚙️
External commands
Design REST and GraphQL APIs with confidence
API design decisions often become inconsistent and hard to maintain. This skill provides clear patterns, templates, and checklists to guide your choices.
Supports: Claude Codex Code(CC)
1
Download the skill ZIP
2
Upload in Claude
Go to Settings → Capabilities → Skills → Upload skill
3
Toggle on and start using
Test it
Using "api-design-principles". Review my user and order endpoints for REST best practices.
Expected outcome:
- Use plural nouns: /api/users and /api/orders
- Replace action paths like /api/createUser with POST /api/users
- Add pagination to list endpoints with page and page_size
- Return 201 Created on successful POST and 204 on DELETE
Using "api-design-principles". How should I structure a GraphQL schema for a blog with users, posts, and comments?
Expected outcome:
- Define User, Post, Comment types with proper relationships
- Use Relay-style cursor pagination for collections
- Create input types for mutations with error payloads
- Add DataLoaders to prevent N+1 queries on relationships
Using "api-design-principles". What status codes should my API return for validation errors?
Expected outcome:
- Return 400 Bad Request for malformed request syntax
- Return 422 Unprocessable Entity for validation failures
- Include field-level error details in the response body
- Use consistent error format across all endpoints
Security Audit
Safev4 • 1/17/2026
This skill contains only educational documentation, code templates, and best practices for API design. All 233 static findings are false positives: 'weak cryptographic algorithm' flags educational password hashing examples; 'backtick execution' misinterprets markdown code formatting; 'system reconnaissance' triggers on legitimate programming terms like fetch/decode; hardcoded URLs/IPs are documentation examples, not actual network calls. No executable code, network calls, or data access patterns pose security risks.
6
Files scanned
2,011
Lines analyzed
2
findings
4
Total audits
Risk Factors
🌐 Network access (7)
⚙️ External commands (134)
references/graphql-schema-design.md:6-35 references/graphql-schema-design.md:35-40 references/graphql-schema-design.md:40-48 references/graphql-schema-design.md:48-51 references/graphql-schema-design.md:51-72 references/graphql-schema-design.md:72-75 references/graphql-schema-design.md:75-99 references/graphql-schema-design.md:99-102 references/graphql-schema-design.md:102-122 references/graphql-schema-design.md:122-127 references/graphql-schema-design.md:127-171 references/graphql-schema-design.md:171-174 references/graphql-schema-design.md:174-185 references/graphql-schema-design.md:185-190 references/graphql-schema-design.md:190-212 references/graphql-schema-design.md:212-215 references/graphql-schema-design.md:215-231 references/graphql-schema-design.md:231-234 references/graphql-schema-design.md:234-254 references/graphql-schema-design.md:254-259 references/graphql-schema-design.md:259-296 references/graphql-schema-design.md:296-299 references/graphql-schema-design.md:299-314 references/graphql-schema-design.md:314-318 references/graphql-schema-design.md:318-343 references/graphql-schema-design.md:343-347 references/graphql-schema-design.md:347-364 references/graphql-schema-design.md:364-369 references/graphql-schema-design.md:369-388 references/graphql-schema-design.md:388-391 references/graphql-schema-design.md:391-404 references/graphql-schema-design.md:404-409 references/graphql-schema-design.md:409-452 references/graphql-schema-design.md:452-455 references/graphql-schema-design.md:455-474 references/graphql-schema-design.md:474-479 references/graphql-schema-design.md:479-493 references/graphql-schema-design.md:493-496 references/graphql-schema-design.md:496-507 references/graphql-schema-design.md:507-510 references/graphql-schema-design.md:510-520 references/graphql-schema-design.md:520-525 references/graphql-schema-design.md:525-531 references/graphql-schema-design.md:531-534 references/graphql-schema-design.md:534-553 references/graphql-schema-design.md:553-562 references/rest-best-practices.md:6-16 references/rest-best-practices.md:16-19 references/rest-best-practices.md:19-28 references/rest-best-practices.md:28-33 references/rest-best-practices.md:33-37 references/rest-best-practices.md:37-40 references/rest-best-practices.md:40-50 references/rest-best-practices.md:50-53 references/rest-best-practices.md:53-60 references/rest-best-practices.md:60-63 references/rest-best-practices.md:63-68 references/rest-best-practices.md:68-71 references/rest-best-practices.md:71-76 references/rest-best-practices.md:76-81 references/rest-best-practices.md:81-97 references/rest-best-practices.md:97-102 references/rest-best-practices.md:102-113 references/rest-best-practices.md:113-116 references/rest-best-practices.md:116-125 references/rest-best-practices.md:125-128 references/rest-best-practices.md:128-136 references/rest-best-practices.md:136-141 references/rest-best-practices.md:141-147 references/rest-best-practices.md:147-150 references/rest-best-practices.md:150-156 references/rest-best-practices.md:156-159 references/rest-best-practices.md:159-164 references/rest-best-practices.md:164-169 references/rest-best-practices.md:169-177 references/rest-best-practices.md:177-180 references/rest-best-practices.md:180-217 references/rest-best-practices.md:217-222 references/rest-best-practices.md:222-227 references/rest-best-practices.md:227-230 references/rest-best-practices.md:230-232 references/rest-best-practices.md:232-237 references/rest-best-practices.md:237-253 references/rest-best-practices.md:253-256 references/rest-best-practices.md:256-257 references/rest-best-practices.md:257-258 references/rest-best-practices.md:258-259 references/rest-best-practices.md:259-260 references/rest-best-practices.md:260-261 references/rest-best-practices.md:261-262 references/rest-best-practices.md:262-263 references/rest-best-practices.md:263-264 references/rest-best-practices.md:264-265 references/rest-best-practices.md:265-266 references/rest-best-practices.md:266-267 references/rest-best-practices.md:267-272 references/rest-best-practices.md:272-283 references/rest-best-practices.md:283-288 references/rest-best-practices.md:288-304 references/rest-best-practices.md:304-309 references/rest-best-practices.md:309-315 references/rest-best-practices.md:315-319 references/rest-best-practices.md:319-329 references/rest-best-practices.md:329-333 references/rest-best-practices.md:333-362 references/rest-best-practices.md:362-366 references/rest-best-practices.md:366-385 SKILL.md:31 SKILL.md:32 SKILL.md:33 SKILL.md:34 SKILL.md:35 SKILL.md:54-57 SKILL.md:57-60 SKILL.md:60-62 SKILL.md:62-65 SKILL.md:65-67 SKILL.md:67-73 SKILL.md:73-90 SKILL.md:90-94 SKILL.md:94-151 SKILL.md:151-155 SKILL.md:155-212 SKILL.md:212-216 SKILL.md:216-242 SKILL.md:242-248 SKILL.md:248-349 SKILL.md:349-353 SKILL.md:353-442 SKILL.md:442-446 SKILL.md:446-487 SKILL.md:487-492 SKILL.md:492 SKILL.md:492-506
Audited by: claude View Audit History →
Quality Score
55
Architecture
90
Maintainability
85
Content
21
Community
100
Security
87
Spec Compliance
What You Can Build
Define new API standards
Create consistent REST and GraphQL rules for a team before implementation.
Review API specifications
Audit specs for naming, versioning, and error handling issues.
Improve API usability
Refine endpoints and schema to reduce client confusion and rework.
Try These Prompts
REST basics review
Review this REST API outline and list naming, method, and status code fixes. Provide a short corrected example.
GraphQL schema check
Evaluate this GraphQL schema for pagination, input types, and error patterns. Suggest improvements with brief examples.
Versioning strategy
Recommend a versioning approach for this API and explain the tradeoffs. Provide a migration checklist.
Design checklist run
Apply an API design checklist to this spec and return pass or fail with fixes for each failed item.
Best Practices
- Document versioning and deprecation rules before launch
- Use consistent error formats with stable error codes
- Paginate all collection endpoints with clear limits
Avoid
- Using POST for read-only operations
- Deeply nested resource paths beyond two levels
- Returning inconsistent error shapes across endpoints
Frequently Asked Questions
Is this compatible with Claude, Codex, and Claude Code?
Yes. The guidance is platform agnostic and works in Claude, Codex, and Claude Code.
What are the limits of this skill?
It provides patterns and templates but does not generate a full working API service.
Can I integrate this with my existing codebase?
Yes. Use the checklist and templates to align your existing endpoints and schema.
Does it access or store sensitive data?
No. It only provides static guidance and examples.
What if my API design is not covered?
Provide your spec and goals, then ask for targeted recommendations.
How does it compare to generic API advice?
It includes concrete REST and GraphQL patterns with checklists and templates.