Skip to content

Add CCN API reference documentation#56

Open
claudioALEPH wants to merge 1 commit intomainfrom
feature/ccn-api-docs
Open

Add CCN API reference documentation#56
claudioALEPH wants to merge 1 commit intomainfrom
feature/ccn-api-docs

Conversation

@claudioALEPH
Copy link
Copy Markdown
Member

Summary

  • Added comprehensive CCN API reference at docs/devhub/api/ccn.md, sourced from the OpenAPI spec (v0.9.3) at http://46.255.204.204:4024/api/docs/
  • Covers all 41 endpoints across 12 sections: Messages, Aggregates, Posts, Storage, Accounts, Prices, Programs, Channels, P2P, IPFS, Metrics, and Info
  • Replaced the broken REST API sidebar link (/devhub/api-reference/rest — 404) with the new CCN API entry

Content source

All endpoint paths, parameters, types, defaults, and descriptions come directly from the CCN's swagger.json OpenAPI spec. No fabricated examples — response formats reference schema names from the spec.

Test plan

  • VitePress build succeeds
  • Verify sidebar link navigates correctly
  • Spot-check endpoints against the live Swagger UI

Create comprehensive CCN API reference page sourced from the OpenAPI
spec (v0.9.3). Covers all 41 endpoints across 12 sections: Messages,
Aggregates, Posts, Storage, Accounts, Prices, Programs, Channels, P2P,
IPFS, Metrics, and Info. Replace broken REST API sidebar link with new
CCN API entry.
Comment thread docs/devhub/api/ccn.md
Each CCN exposes the API on its HTTP port. The public API endpoints are:

```
https://api1.aleph.cloud
Copy link
Copy Markdown
Member

@aliel aliel Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown

@foxpatch-aleph foxpatch-aleph left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good addition that fills a real gap (replacing a broken 404 link with actual content). The documentation is well-structured and consistently formatted. A few accuracy issues worth addressing: a contradictory min_balance constraint, a misplaced endpoint, inconsistent array parameter notation, and a POST endpoint with no documented request body.

docs/devhub/api/ccn.md (line 519): min_balance lists min: 1 but a default of 0. A minimum of 1 means the default of 0 is not a valid value — these are contradictory. If the API truly enforces min: 1, the default should be omitted or set to 1. Same issue appears in the GET /api/v0/credit_balances table (~line 543). Please verify against the OpenAPI spec.

docs/devhub/api/ccn.md (line 672): "Get Resource Consumed Credits" (GET /api/v0/messages/{item_hash}/consumed_credits) is placed under the Accounts section, but its URL path is under /messages/. This will confuse users looking for it under Messages. Consider moving it to the Messages section, or at minimum adding a cross-reference there.

docs/devhub/api/ccn.md (line 443): The Address Stats (v0) endpoint documents its parameter as addresses[] (PHP/HTML array notation), while every other multi-value parameter in this file uses comma-separated strings (e.g., addresses in List Messages). If v0 genuinely expects repeated query params (?addresses[]=0x1&addresses[]=0x2) rather than a comma-separated string, this difference deserves a note — it's a real usability gotcha.

docs/devhub/api/ccn.md (line 237): The sortBy field for GET /api/v0/aggregates shows the default (last_modified) but unlike other endpoints (e.g., List Messages lists time, tx-time) does not enumerate the allowed values. Worth adding the full set of valid options.

docs/devhub/api/ccn.md (line 696): POST /api/v0/price/recalculate has no documented request body. This is unusual for a POST endpoint — does it accept filters (e.g., address, date range, message type) or is it an admin-only no-body operation? If it requires authorization or has optional parameters, those should be documented here.

docs/devhub/api/ccn.md (line 761): Minor organizational note: the P2P section contains a single endpoint whose path is POST /api/v0/ipfs/pubsub/pub — an IPFS-namespaced path. Consider either merging it into the IPFS section or adding a brief note explaining why a P2P pubsub operation lives under /ipfs/ (historical naming, shared transport, etc.).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants