Skip to content
This repository has been archived by the owner on Jan 13, 2025. It is now read-only.

[docs] new JSON RPC API docs format #29772

Merged
merged 28 commits into from
Jan 26, 2023

Conversation

nickfrosty
Copy link
Contributor

@nickfrosty nickfrosty commented Jan 19, 2023

Problem

The JSON RPC API docs are difficult to navigate and consume. It should be easier to see the actual method docs and examples of how to use the method.

Changes

  • created a new /api landing page (see picture below)
  • creates a new display format in a "side-by-side" style format (picture below of what it looks like)
  • each RPC method is segmented out into separate markdown "partial" files (currently living in src/api)
  • the RPC methods for http and websocket methods have been moved to different pages
  • custom sidebar for each of the /api pages to show only the methods related to the current viewed page (e.g. http or websocket methods)
  • verified all recent changes of the JSON RPC page have been implemented into the newly formatted partials
    • verified commits affecting the JSON rpc page up until Jan 18, 2023 (which are all since this PR was opened)
    • history of changes here
  • added a description of the space value returned for accounts to the API docs

NOTE:
This updated display method will also pave the way to enable the core docs to have each of the client API docs on the same page, with a client "language" selector the user can use to view all the respective API docs for each client (e.g. JSON RPC via cURL, JavaScript, Rust)

Workflow for adding/updating RPC method doc pages

Making updates to the individual docs for each method will be inside of their respective "partial" MDX file, located in the respective src/api folder. See this example of the getAccountInfo method doc for reference

Each of these markdown "partials" will be linked withing the corresponding api doc page (similar to importing a component in React, per the Docusaurus docs). Here is an example for the getAccountInfo method

Screenshot of the proposed new format:

API home page (located at url /api)

Screenshot from 2022-10-22 08-46-57

Example of the "side-by-side" view (this example is located at /api/http#getaccountinfo)

Screenshot from 2022-10-22 08-40-04

Read more "details" component expanded:

Screenshot from 2022-10-22 08-58-08

@mergify mergify bot added the community Community contribution label Jan 19, 2023
@mergify mergify bot requested a review from a team January 19, 2023 01:02
@nickfrosty nickfrosty marked this pull request as ready for review January 19, 2023 01:05
@jacobcreech jacobcreech requested review from jacobcreech and removed request for a team January 19, 2023 04:27
@jacobcreech
Copy link
Contributor

There's a number of broken links on the page due to pointing to /api instead of /api/http. Are you not worried about the weird navigation going from /developers, clicking on JSON RPC API from the sidebar and being thrown into a new sidebar?

@nickfrosty
Copy link
Contributor Author

nickfrosty commented Jan 20, 2023

@jacobcreech Incorrect links have been fixed. Including the final removal of the jsonrpc-api.md file and an outdated reference to an RPC method on the edge docs.
Also corrected the linking to the filters criteria object on 2 pages.

I think the sidebar change is a bit annoying, but the best case. Since the new RPC API sidebar is so large and different, having all of the RPC methods also displayed on the regular developer sidebar would be far too cumbersome. In the future, the developers sidebar will be slimmed down to help minimize the visual page change

jacobcreech
jacobcreech previously approved these changes Jan 24, 2023
Copy link
Contributor

@jacobcreech jacobcreech left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome work! In regards to the page switching on us between developers -> RPC, we should consider making RPC API its own thing as part of #29744

@jacobcreech jacobcreech added the CI Pull Request is ready to enter CI label Jan 24, 2023
@solana-grimes solana-grimes removed the CI Pull Request is ready to enter CI label Jan 24, 2023
@mergify mergify bot dismissed jacobcreech’s stale review January 24, 2023 18:04

Pull request has been modified.

@jacobcreech jacobcreech added the CI Pull Request is ready to enter CI label Jan 24, 2023
@solana-grimes solana-grimes removed the CI Pull Request is ready to enter CI label Jan 24, 2023
@jacobcreech jacobcreech added the CI Pull Request is ready to enter CI label Jan 25, 2023
@solana-grimes solana-grimes removed the CI Pull Request is ready to enter CI label Jan 25, 2023
@jacobcreech jacobcreech added the CI Pull Request is ready to enter CI label Jan 26, 2023
@solana-grimes solana-grimes removed the CI Pull Request is ready to enter CI label Jan 26, 2023
Copy link
Contributor

@jacobcreech jacobcreech left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update! Looking forward to seeing how this does

@jacobcreech jacobcreech merged commit 9b27002 into solana-labs:master Jan 26, 2023
mergify bot pushed a commit that referenced this pull request Jan 26, 2023
* feat: added api page

* fix: api redirects

* feat: websocket page and partials

* feat: deprectated partials

* feat: http method partials

* fix: more deprecated partials

* feat: codeblock component and styles

* feat: api http methods page

* feat: sidebar

* refactor: proposal api links

* refactor: internal linking

* refactor: more internal links

* refactor: internal link and note cards

* refactor: local links

* refactor: local links and auto save prettier

* feat: added numNonVoteTransaction data details

* fix: updated getRecentPrioritizationFees

* fix: corrected wording

* fix: version typo

* fix: commitment links

* fix: parsed response links

* fix: dangling links

* refactor: filter criteria

* docs: removed jsonrpc-api.md file

* fix: dangling links

* style: removed whitespaces for CI

* style: removed whitespace

* style: fixed whitespaces

(cherry picked from commit 9b27002)

# Conflicts:
#	docs/src/developing/clients/jsonrpc-api.md
#	docs/src/developing/transaction_confirmation.md
#	docs/src/developing/versioned-transactions.md
@steviez
Copy link
Contributor

steviez commented Feb 13, 2023

Stumbled upon this today and leaving a note to say I'm a fan of the change!
image

@nickfrosty nickfrosty added v1.14 and removed v1.14 labels Apr 6, 2023
yihau pushed a commit to yihau/solana that referenced this pull request Apr 7, 2023
* feat: added api page

* fix: api redirects

* feat: websocket page and partials

* feat: deprectated partials

* feat: http method partials

* fix: more deprecated partials

* feat: codeblock component and styles

* feat: api http methods page

* feat: sidebar

* refactor: proposal api links

* refactor: internal linking

* refactor: more internal links

* refactor: internal link and note cards

* refactor: local links

* refactor: local links and auto save prettier

* feat: added numNonVoteTransaction data details

* fix: updated getRecentPrioritizationFees

* fix: corrected wording

* fix: version typo

* fix: commitment links

* fix: parsed response links

* fix: dangling links

* refactor: filter criteria

* docs: removed jsonrpc-api.md file

* fix: dangling links

* style: removed whitespaces for CI

* style: removed whitespace

* style: fixed whitespaces
jacobcreech pushed a commit that referenced this pull request Apr 7, 2023
* [docs] new JSON RPC API docs format (#29772)

* feat: added api page

* fix: api redirects

* feat: websocket page and partials

* feat: deprectated partials

* feat: http method partials

* fix: more deprecated partials

* feat: codeblock component and styles

* feat: api http methods page

* feat: sidebar

* refactor: proposal api links

* refactor: internal linking

* refactor: more internal links

* refactor: internal link and note cards

* refactor: local links

* refactor: local links and auto save prettier

* feat: added numNonVoteTransaction data details

* fix: updated getRecentPrioritizationFees

* fix: corrected wording

* fix: version typo

* fix: commitment links

* fix: parsed response links

* fix: dangling links

* refactor: filter criteria

* docs: removed jsonrpc-api.md file

* fix: dangling links

* style: removed whitespaces for CI

* style: removed whitespace

* style: fixed whitespaces

(cherry picked from commit 9b27002)

# Conflicts:
#	docs/src/developing/clients/jsonrpc-api.md
#	docs/src/developing/transaction_confirmation.md
#	docs/src/developing/versioned-transactions.md

* rm docs/src/developing/clients/jsonrpc-api.md

* fix docs/src/developing/versioned-transactions.md

---------

Co-authored-by: Nick Frostbutter <[email protected]>
Co-authored-by: yihau <[email protected]>
bw-solana pushed a commit to bw-solana/solana that referenced this pull request Jan 10, 2025
…ana-labs#29939)

* [docs] new JSON RPC API docs format (solana-labs#29772)

* feat: added api page

* fix: api redirects

* feat: websocket page and partials

* feat: deprectated partials

* feat: http method partials

* fix: more deprecated partials

* feat: codeblock component and styles

* feat: api http methods page

* feat: sidebar

* refactor: proposal api links

* refactor: internal linking

* refactor: more internal links

* refactor: internal link and note cards

* refactor: local links

* refactor: local links and auto save prettier

* feat: added numNonVoteTransaction data details

* fix: updated getRecentPrioritizationFees

* fix: corrected wording

* fix: version typo

* fix: commitment links

* fix: parsed response links

* fix: dangling links

* refactor: filter criteria

* docs: removed jsonrpc-api.md file

* fix: dangling links

* style: removed whitespaces for CI

* style: removed whitespace

* style: fixed whitespaces

(cherry picked from commit 9b27002)

# Conflicts:
#	docs/src/developing/clients/jsonrpc-api.md
#	docs/src/developing/transaction_confirmation.md
#	docs/src/developing/versioned-transactions.md

* rm docs/src/developing/clients/jsonrpc-api.md

* fix docs/src/developing/versioned-transactions.md

---------

Co-authored-by: Nick Frostbutter <[email protected]>
Co-authored-by: yihau <[email protected]>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
community Community contribution need:merge-assist
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants