skills.rest
TencentBlueKing
TencentBlueKingOFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-interface-design

Standardize RESTful API design with URL conventions, HTTP methods, and error codes.

2.5k|521|Updated May 29, 2019
One-click install
npx skills add https://github.com/TencentBlueKing/bk-ci --skill api-interface-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-interface-design
Source: https://github.com/TencentBlueKing/bk-ci/tree/main/ai/skills/api-interface-design
Command: npx skills add https://github.com/TencentBlueKing/bk-ci --skill api-interface-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design teams often struggle with inconsistent API designs across services, causing integration friction and poor developer experience. This Skill provides a unified RESTful API design standard, guiding resource modeling, URL naming, HTTP methods, error codes, and versioning to ensure coherence across projects.

Core Features & Use Cases

  • RESTful API design principles and best practices
  • URL naming conventions and resource modeling
  • Consistent error codes and versioning schemes
  • Reference templates for interface contracts and documentation
  • Suitable for API reviews, interface definition, and documentation tasks

Quick Start

Define a new API endpoint following the guidelines: determine scope, map to a resource, choose an HTTP method, craft request and response structures, and assign standardized error codes. Use the examples for a user-facing pipeline resource at /user/pipelines with a paginated list and a suitable info response. Ensure the interface contracts are documented in Swagger/OpenAPI with versioning considerations.

Frequently Asked Questions about api-interface-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design consistent RESTful APIs across multiple services?▼

Design consistent RESTful APIs by standardizing URL conventions, resource modeling, HTTP methods, error codes, and versioned endpoints to eliminate cross-service integration friction.

What are the best practices for RESTful URL naming and resource modeling?▼

RESTful URL naming best practices involve mapping actions to resources, choosing appropriate HTTP methods, and crafting structured request and response payloads to ensure clear interface contracts.

How should I structure error codes and versioned endpoints in my API?▼

Structure error codes and versioned endpoints by enforcing standardized error responses and versioned paths, ensuring coherent API evolution and predictable failure handling across services.

Can I generate Swagger or OpenAPI documentation from these RESTful API definitions?▼

Yes, you can generate Swagger-ready annotations and OpenAPI documentation by following the structured response templates and versioned endpoint guidelines provided by this standard.

Does this RESTful API standard support paginated list responses?▼

Yes, this RESTful API standard supports paginated list responses. It provides reference templates for interface contracts, including examples for paginated user-facing pipeline resources.

When do I need a standardized RESTful API design for my project?▼

You need a standardized RESTful API design when integration friction arises from inconsistent interfaces across services, requiring unified principles for API reviews and documentation tasks.

Related Skills

camoneartcamoneart
5

architecture-patterns

Apply Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to backend systems.

Community
Advanced
dinoudondinoudon

api-documentation

Generates API references and SDK scaffolds from OpenAPI specifications.

Community
Advanced
VanhPokerVanhPoker

rest-api-expert

Design REST APIs with resource-based endpoints, HTTP status codes, and OpenAPI specs.

Community
Advanced
futuregeraldfuturegerald
6

api-design-principles

Guide REST and GraphQL API design with versioning and error-handling patterns.

Community
Advanced