Api Interface Design

What it does

This skill assists with designing API interfaces, specifically within the context of building frontend user interfaces and related workflows. It provides guidance on path formats, return structures (including Result<T> for success/failure and Page<T> for pagination), error code conventions (e.g., 2100013 for invalid parameters), and HTTP status code usage. The skill is intended to help define Resource classes and data structures for API requests and responses.

When to use it

• Designing RESTful API interfaces.
• Defining Resource classes within an API structure.
• Understanding and adhering to the specified error code format (21(Platform)01(Service)001(Business Code)).
• Designing request/response data structures for APIs.

Key capabilities

• Provides path formatting guidelines: /scope/{resource}/{resourceId}/{subResource} with prefixes like /user/, /service/, /build/, and /open/.
• Defines standardized return formats using Result<T> (status, message, data) and Page<T> (count, page, pageSize, totalPages, records).
• Specifies an error code format: 21(Platform)01(Service)001(Business Code).
• Outlines HTTP status code usage guidelines.

Example prompts

• "Show me the recommended path format for a user pipeline resource."
• "What is the structure of a Result<T> object?"
• "Explain the error code format and give an example."

Tips & gotchas

• This skill focuses on API design, not implementation. For backend microservice development, use the 01-backend-microservice-development skill instead.
• Parameter validation rules should be handled by the common-technical-practices skill.