Skip to content

add updated v2 schema#10

Open
laviniat1996 wants to merge 1 commit intotoncenter:mainfrom
laviniat1996:main
Open

add updated v2 schema#10
laviniat1996 wants to merge 1 commit intotoncenter:mainfrom
laviniat1996:main

Conversation

@laviniat1996
Copy link
Copy Markdown

Adds v2.json next to the existing v2.yaml. The YAML is not deleted yet, but v2.json should be the source of truth from now on. Future updates should go in the JSON file, following the same conventions.

Changes

Same 34 endpoints, same API, but the spec just actually documents it now.

Descriptions: Every endpoint, parameter, and response has a real description.

Typed responses: The YAML used TonlibResponse for every single 200 response (65 references). Now each endpoint has its own response schema.

Error responses: Instead of one generic default error, there are now 21 specific error responses (401, 403, 404, 409, 422 variants per category, 429, 500 variants, 504, 542) with descriptions of what triggers each.

Removed duplicate POSTs: The YAML duplicated every GET as a POST under the rpc tag. Removed all of those. POST is now only on the 6 endpoints that actually need it: jsonRPC, sendBoc, sendBocReturnHash, estimateFee, runGetMethod, runGetMethodStd.

Servers block: Added mainnet (toncenter.com) and testnet (testnet.toncenter.com) so Swagger UI / Postman work out of the box.

Conventions for future edits

  • Descriptions should explain what the endpoint does and returns, not just repeat the name
  • Each endpoint gets its own response schema, don't fall back to TonlibResponse
  • Error responses should be specific, use the 422_* pattern
  • POST only for endpoints that mutate state or need a request body
  • Add examples for non-obvious formats (addresses, hashes, BOCs)

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.

1 participant