Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

api-design

/api-design

Podaje dobre praktyki projektowania API inteligentnych kontraktów CosmWasm: typy komunikatów, interfejsy execute i query oraz ergonomia API.

Repozytorium
contracts ↗
Licencja
BSD-3-Clause
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

BSD-3-Clause, otwarta.

Co robi i kiedy

Podaje dobre praktyki projektowania API inteligentnych kontraktów CosmWasm: typy komunikatów, interfejsy execute i query oraz ergonomia API.

Oryginalny opis (EN)

Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.

Jak działa

  1. Core Principles
  2. Message Type Patterns
  3. Abstract SDK Integration
  4. Documentation Standards
  5. Serde Patterns
Sekcje z nagłówków SKILL.md, w oryginale · 193 linii, 506 słów
Podgląd SKILL.md
---
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,
```

Wersje

RepozytoriumWynikLicencja
Ta strona · axone-protocol/contracts100BSD-3-Clause
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

Migawka bazy z 13.11.2026 · wersja paczki 029b683a76f8 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100api
    Podaje wzorce i dobre praktyki projektowania REST API przy tworzeniu endpointów i tras.
  • 100cosmwasm-contract
    Opisuje strukturę kontraktów Axone i wzorce Abstract SDK: szkielet i refaktoryzacja kontraktów, granice warstw, podpinanie entrypointów AppContract oraz metadane i odpowiedzi modułów.
  • 100rust-testing
    Podpowiada wzorce testów jednostkowych, integracyjnych i danych testowych dla kontraktów CosmWasm w projekcie Axone.
  • 100api-design-patterns
    Podaje wzorce projektowania API RESTful, obsługi błędów, wersjonowania i dobrych praktyk, także przy przeglądzie endpointów.
  • 100api-design-assistant
    Projektuje i przegląda API, sugerując endpointy, parametry, typy zwracane i dobre praktyki, z naciskiem na REST i specyfikacje OpenAPI.
  • 100postgresql
    Projektuje schematy specyficzne dla PostgreSQL: dobre praktyki, typy danych, indeksowanie, ograniczenia i wzorce wydajności oraz dodatkowe możliwości silnika.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.