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.
closes #1049