Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Design what should be included within the SDK method docs. #290

Open
johnnymatthews opened this issue Dec 18, 2024 · 0 comments
Open

Design what should be included within the SDK method docs. #290

johnnymatthews opened this issue Dec 18, 2024 · 0 comments

Comments

@johnnymatthews
Copy link
Collaborator

Child of #287

This issue describes the type of content we need to create for the API/SDK reference section of this issue's parent issue (#287).

Here's the stuff we need to display:

  • Method descriptions
  • Parameter explanations
  • Return value details
  • Error handling

Let's dive into a bit more detail for each fo these sections.

Method descriptions

These should be a clear and concise explanation of the method functionality. Essentially, we need to explain the method's role in the broader SDK context, and mention any side effects or important behavioral notes.

createAccount(params)
- Creates a new account.
- Generates a unique address identifier.
- Triggers account initialization workflows.

Parameters

Parameter explanation should include:

  • Data type
  • Whether it's required or optional
  • Default value (if applicable)
  • Validation rules
  • Example values
  • Constraints

For example:

Parameters:
- account: string
  - Required
  - Must be unique
  - 3-50 characters long
  - Allowed characters: alphanumeric 
  - Example: "0x2907y4fb8tspiubteciu3296t"

Return values

  • Specify exact return type.
  • Describe what the return represents.
  • Show potential return variations.
  • Include example return structures.
```json
Returns: accountObject
{
  public_address: string
  private_key: string  
  mnemonic: string
  derivationKey: string 
}
```

Return Scenarios:

- Successful creation returns full UserAccount.
- Validation failure returns null

Error handling

Essentially, how does the SDK handle errors? Or do it not, and expects the devs to handle them instead? If the SDK does handle errors we need to list the following:

  • Error Type
  • Error Code
  • Description
  • Potential Cause
  • Recommended Action
ValidationError (Code: 400)
  - Occurs when input parameters are invalid
  - Triggered by:
    - Invalid address
    - Invalid invalid mnemonic
  - Action: Validate inputs before submission

SystemError (Code: 500)
   - Unexpected server-side issues
   - Triggered by:
     - Cannot contact Entropy node.
     - Entropy node returns invalid or unexpected data.
   - Action: Retry.
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

No branches or pull requests

1 participant