refactor: API protocol

[MaxMoskalenko]

This PR was partially started as a fix of this issue #277. But there is even a bigger issue in the current API protocol: there are no strict standards for params field. Therefore right now params field could contain string, array, object or any other JSON-supported data structure.

In my opinion, it makes further code maintenance and developing harder. As adding new field to non-object structure (e.g. add metadata object to array structure in get_channels resp.) will require changes on sdk side and could cause type and compilation errors on product (that uses nitrolite) side. Also support backward compatibility for these changes would create huge amount of legacy code (aka code debt). So it would be nice to solve this issue ASAP

PS. is there are any incentives to wrap params in array, could we simplify it by making: [id, "message", params{}, ts] instead of [id, "message", [params{}], ts] ?

[gemini-code-assist]

Summary of Changes

Hello @MaxMoskalenko, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a significant architectural concern by proposing and documenting a standardized API protocol, particularly for the params field in both requests and responses. The goal is to enforce a consistent object-based structure for API data, especially for list-returning endpoints, which will greatly improve future code maintenance, development, and backward compatibility by avoiding the current ad-hoc usage of various JSON data structures. This is a foundational step towards a more robust and scalable API.

Highlights

• API Response Standardization: I've standardized the structure of the params field in API responses for endpoints that return lists of items. Previously, these often returned a direct array of items (e.g., [[item1, item2]]). Now, they consistently return an array containing a single object, where the list of items is nested under a descriptive key (e.g., [{ "channels": [item1, item2] }]). This makes the API more predictable and extensible.
• Pagination Metadata: For paginated endpoints, I've introduced a metadata object within the standardized response structure. This object provides crucial pagination details such as page, per_page, total_count, and page_count, enhancing client-side pagination logic.
• API Request Parameter Clarification: I've updated the documentation for several API request examples (get_channels, get_app_sessions, get_ledger_entries, get_ledger_transactions) to explicitly show that optional parameters should be provided within an object, even if the request can be empty.
• Documentation-First Approach: The changes in this pull request are primarily documentation updates in API.md, reflecting the proposed API standard. I've also added TODO comments in the Go codebase (rpc_node.go, rpc_router_private.go) to guide future implementation work towards this new standard.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a standard for the API's params field in responses, enhancing consistency and extensibility. The changes in API.md document the new structure, wrapping response data in a named object. I've provided suggestions to improve consistency across endpoints and to implement the new error format.

[gemini-code-assist]

The TODO comment indicates a need to align the error message format with the new API standard. To ensure consistency across the API, update the error responses to follow the new standard, where params is an array containing an object with an error key.

    c.Message.Res = &RPCData{
        RequestID: c.Message.Req.RequestID,
        Method:    "error",
        Params:    []any{map[string]string{"error": message}},
        Timestamp: uint64(time.Now().UnixMilli()),
    }

[gemini-code-assist]

The response for get_app_definition should follow the new standard, wrapping the app_definition in an object with a key, similar to other endpoints like get_channels and get_app_sessions. This ensures consistency across the API.

Consider the following structure:

{
  "res": [1, "get_app_definition", [{
    "app_definition": {
      "protocol": "NitroRPC/0.2",
      "participants": [
        "0xAaBbCcDdEeFf0011223344556677889900aAbBcC",
        "0x00112233445566778899AaBbCcDdEeFf00112233"
      ],
      "weights": [50, 50],
      "quorum": 100,
      "challenge": 86400,
      "nonce": 1
    }
  }], 1619123456789],
  "sig": ["0xabcd1234..."]
}

[alessio]

Looks ok to me. Please ask for someone else's opinion too before merging 🙏

[philanton]

Right now that is only proposal, do you plan to change implementation in this PR too?
I'm just not sure whether that's a right decision to merge it before actual logic is done, - documentation will be out of sync with application

[mnaichuk]

1. I don't see any reason to wrap params in an array, so this change is good for me

[mnaichuk]

and I think API changes should be more collaborative, and we need @akushniruk opinion here too, not only BE guys

[dimast-x]

It's same field. As I know currently SDK is using participant field, but this field must be deprecated and account_id field should be used. If we do so many changes in this PR, I suggest dropping participant and keeping account_id as it was intended

[mnaichuk]

rebase please

[nksazonov]

Please,

• rebase on feat: v0.3.0 #299 now
• rebase on feat: v0.3.0 #299 once "join(...) simplification" is merged
• reopen PR to feat/v0.3.0 branch