update API v2 field descriptions #1469
Conversation
|
Skipping AI review because no docs changes in md, mdx, or docs.json |
laviniat1996
changed the title
laviniat1996
added
the
3p
| ], | ||
| "summary": "JSON-RPC endpoint", | ||
| "description": "All API methods are available through this single endpoint using JSON-RPC 2.0 protocol. Send the method name in the `method` field and parameters as a dictionary in `params`. Useful when you need to call multiple methods in sequence or prefer JSON-RPC over REST.", |
There was a problem hiding this comment.
Authorizations description shouldn't be empty:
Example of a good definition:
| "summary": "JSON-RPC endpoint", | ||
| "description": "All API methods are available through this single endpoint using JSON-RPC 2.0 protocol. Send the method name in the `method` field and parameters as a dictionary in `params`. Useful when you need to call multiple methods in sequence or prefer JSON-RPC over REST.", | ||
| "operationId": "jsonRPC_post", | ||
| "requestBody": { |
There was a problem hiding this comment.
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/json-rpc-endpoint
Result field seems strange and broken:
Does it really have two options?
| ], | ||
| "summary": "Detect address", |
There was a problem hiding this comment.
The field definition is wrong, which works from ANY form of TON Address:
example:
curl --request POST \
--url https://toncenter.com/api/v2/detectAddress \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"address": "0:c78b3eb54a55243d4efe411f0bb0101a8da61904a89c48212f81ff32006b2dc1"
}
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/detect-address
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc...), base64 bounceable (EQ...), base64 non-bounceable (UQ...), and URL-safe variants.", | ||
| "operationId": "detectAddress_post", | ||
| "requestBody": { |
There was a problem hiding this comment.
Let's find a more detailed explanation of this field for devs. Even if this is not for external use, it should be documented clearly:
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/detect-address
| "description": "Similar to previous one but tries to parse additional information for known contract types. This method is based on tonlib's function *getAccountState*. For detecting wallets we recommend to use *getWalletInformation*.", | ||
| "operationId": "get_extended_address_information_getExtendedAddressInformation_get", | ||
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc), base64 bounceable (EQ), base64 non-bounceable (UQ), and URL-safe variants.", |
There was a problem hiding this comment.
All fields should be fully self-descriptive without dependency on other fields:
Example:
description: User-friendly bounceable address in standard base64 encoding.
description: User-friendly bounceable address, base64-encoded and safe for use in URLs.
| "operationId": "get_extended_address_information_getExtendedAddressInformation_get", | ||
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc), base64 bounceable (EQ), base64 non-bounceable (UQ), and URL-safe variants.", | ||
| "operationId": "detectAddress_get", |
There was a problem hiding this comment.
Since this is related to the user-friendly address flag, it should be accurately explained, that this is representation. This flag not 100% defined, whether the account of qiured address belongs only to the Testnet or Mainnet, because the address itself matches within both networks.
| ], | ||
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc...), base64 bounceable (EQ...), base64 non-bounceable (UQ...), and URL-safe variants.", | ||
| "operationId": "detectAddress_post", |
There was a problem hiding this comment.
For the /api/v2/detectAddress method, address description:
It's better to make a compact definition and add a link:
Account address in raw format (e.g., 0:ca6e321c...) or User-friendly format (e.g., EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF)
| "hash": { | ||
| "name": "hash", | ||
| "in": "query", | ||
| "description": "A 256-bit hash in hex (64 chars) or base64 (44 chars) format. Used to identify blocks, transactions, and messages uniquely.", |
There was a problem hiding this comment.
This description duplicated with another one in render:
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/ExtraCurrencyBalance" | ||
|
|
There was a problem hiding this comment.
Let's define response description with the "Returns" verb. In this way, we avoid overusing "Response," and the description sounds more direct.
Example: Returns the hash of the requested resource in all supported formats (hex, base64, base64 URL-safe).
Can we remove the word "OK" from this description? "OK" is an excess word here.
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/ExtraCurrencyBalance" | ||
|
|
There was a problem hiding this comment.
A Boolean parameter is better suited to describe straightforward boolean values:
Example: Returns true if the request succeeded; otherwise false. See the error field for details.
| } | ||
| } | ||
| ], | ||
| "description": "The response data. Only present when `ok` is true. " |
There was a problem hiding this comment.
true should be formatted as code.
| "b64": { | ||
| "type": "string", | ||
| "title": "base64 form", | ||
| "description": "Standard base64 encoding." |
There was a problem hiding this comment.
Add a full self-defined description for each child field.
| "summary": "Pack address", | ||
| "description": "Converts a raw address to user-friendly base64 format. Raw addresses use the format `workchain:hex` (e.g., `0:abc...`). The packed format is shorter and includes a checksum for error detection.", | ||
| "operationId": "packAddress_post", | ||
| "requestBody": { |
There was a problem hiding this comment.
Duplicated address field description
| "properties": { | ||
| "hash": { | ||
| "$ref": "#/components/schemas/TonHash", | ||
| "description": "Unique identifier hash for this object." |
There was a problem hiding this comment.
This object - unclear. Let's specify a list of potential entities here: message, transaction, account?
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/ExtraCurrencyBalance" | ||
|
|
There was a problem hiding this comment.
If we have no child object specified, let's describe this in the overall description. Add self-completed description here, what will be in this data by type, encoding e.t.c.
closes #1049