api-design
/api-design
Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.
- Author
- axone-protocol ↗
- Repository
- contracts ↗
- Licence
- BSD-3-Clause
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
BSD-3-Clause, otwarta.
What it does and when to use it
Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.
Original author description
Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.
How it works
- Core Principles
- Message Type Patterns
- Abstract SDK Integration
- Documentation Standards
- Serde Patterns
SKILL.md preview
---
name: api-design
description: Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.
license: BSD-3-Clause
metadata:
author: axone.xyz
version: "1.0"
---
# CosmWasm API Design Best Practices
## Core Principles
1. **Minimalism** - Include only what's necessary; avoid bloated APIs
2. **Clarity** - Names should be self-documenting
3. **Consistency** - Follow established patterns across all contracts
4. **Documentation** - Every public type and field must have doc comments
## Message Type Patterns
### InstantiateMsg
```rust
/// Contract instantiation message
#[cosmwasm_schema::cw_serde]
#[derive(Default)]
pub struct MyContractInstantiateMsg {
/// Optional configuration parameter with sensible default
#[serde(default)]
pub some_config: Option<String>,
}
```
**Guidelines:**
- Derive `Default` when possible for easier testing
- Use `#[serde(default)]` for optional fields
- Keep required fields minimal
- Document each field
### ExecuteMsg
```rust
/// Contract execute messages
#[cosmwasm_schema::cw_serde]
#[derive(cw_orch::ExecuteFns)]
pub enum MyContractExecuteMsg {
/// Update the contract configuration
UpdateConfig {
/// New admin address (optional)
new_admin: Option<String>,
},
/// Process an action with the given parameters
ProcessAction {
/// Unique identifier for the action
action_id: String,
/// Amount to process
amount: Uint128,
},
}
```
**Guidelines:**
- Use verb-based names (Update, Process, Create, Remove)
- Group related parameters in structs if >3 fields
- Document each variant AND each field
- Derive `ExecuteFns` for cw-orch integration
### QueryMsg
```rust
/// Contract query messages
#[cosmwasm_schema::cw_serde]
#[derive(cw_orch::QueryFns, QueryResponses)]
pub enum MyContractQueryMsg {
/// Get the current configuration
#[returns(ConfigResponse)]
Config {},
/// Get item by ID
#[returns(ItemResponse)]
Item {
/// The item identifier
id: String,
},
/// List all items with pagination
#[returns(ItemsResponse)]
Items {
/// Start after this ID for pagination
start_after: Option<String>,
/// Maximum number of items to return
limit: Option<u32>,
},
}
```
**Guidelines:**
- Always include `#[returns(ResponseType)]` attribute
- Use noun-based names for queries
- Include pagination for list queries (`start_after`, `limit`)
- Derive `QueryFns` and `QueryResponses`
### Response Types
```rust
#[cosmwasm_schema::cw_serde]
pub struct ConfigResponse {
/// Current admin address
pub admin: Addr,
/// Whether the contract is paused
pub paused: bool,
}
#[cosmwasm_schema::cw_serde]
pub struct ItemsResponse {
/// List of items
pub items: Vec<ItemInfo>,
}
```
**Guidelines:**
- Response types should mirror what clients need
- Use specific types (Addr, Uint128) not strings
- Document all fields
## Abstract SDK Integration
Use the `app_msg_types!` macro to generate wrapper types:
```rust
use crate::contract::MyContract;
use cosmwasm_schema::QueryResponses;
// Generates ExecuteMsg, QueryMsg, InstantiateMsg wrappers
abstract_app::app_msg_types!(MyContract, MyContractExecuteMsg, MyContractQueryMsg);
```
## Documentation Standards
### Rust Doc Comments
```rust
/// Brief one-line description of the variant.
///
/// Optional longer description that explains:
/// - When to use this
/// - Side effects
/// - Related messages
///
/// # Errors
///
/// Returns `ContractError::Unauthorized` if caller is not admin.
```
### Field Documentation
Every field must have a doc comment:
- Describe what the field represents
- Mention default values if applicable
- Note any constraints (min/max values, format)
## Serde Patterns
### Optional Fields with Defaults
```rust
#[serde(default)]
pub optional_field: Option<String>,
#[serde(default = "default_limit")]
pub limit: u32,
fn default_limit() -> u32 {
10
}
```
### Flatten for Nested Configs
```rust
#[cosmwasm_schema::cw_serde]
pub struct InstantiateMsg {
#[serde(flatten)]
pub base_config: BaseConfig,
pub custom_field: String,
}
```
### Rename for JSON Clarity
```rust
#[serde(rename = "owner")]
pub owner_addr: Addr,
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · axone-protocol/contracts | 100 | BSD-3-Clause |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Database snapshot: 13.11.2026 · package version 029b683a76f8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api
RESTful API design patterns and best practices. Use when creating endpoints, designing APIs, or implementing routes. - 100cosmwasm-contract
Axone contract structure and Abstract SDK patterns. Use when scaffolding or refactoring contracts, deciding layer boundaries, wiring AppContract entrypoints, or adding module metadata and replies. - 100rust-testing
Patterns for Rust testing in Axone CosmWasm contracts. Use when adding unit tests, integration tests, data-driven cases, or coverage-oriented test scenarios. - 100api-design-patterns
RESTful API design, error handling, versioning, and best practices. Use when designing APIs, reviewing endpoints, implementing error responses, or setting up API structure. Triggers on "design API", "review API", "REST best practices", or "API patterns". - 100api-design-assistant
Design and review APIs with suggestions for endpoints, parameters, return types, and best practices. Use when designing new APIs from requirements, reviewing existing API designs, generating API documentation, or getting implementation guidance. Supports REST APIs with focus on… - 100postgresql
Design PostgreSQL-specific schemas covering best practices, data types, indexing, constraints, performance patterns, and advanced features. Use when designing or optimizing PostgreSQL databases.