RFC : feature design for fullnodeAPI <=> networkexplorerAPI <=> networkexplorerWeb

[sunnygleason]

Problem:

• we want network explorer to be a stable, "independent" view across networks
• network explorer frequently degrades in a non-graceful manner when (a) different fullnode versions are deployed across different stages, leading to (b) network explorer API not being able to access the data in the form it needs

Solution (proposed):

• We should make sure fullnode, network explorer API, network explorer webapp all advertise versions
• The API provides endpoints with versioned result types roughly corresponding to Views
• Each View (including nested views) uses API endpoints to obtain versioned result types
• A view typically needs the most recent result type
• Results are either present (at latest version), partial (previous version), or absent
• The view should handle the different cases and either display the (1) full view, (2) degraded view (if it's worth it), or (3) some kind of resource unavailable + reason message

Additional thoughts:

• we probably want to stick to 1:1 API operation to view as much as possible to avoid sideways/partial failure cases - prefer to synthesize data in network explorer API where necessary

[mvines]

fullnode already advertises a semver version so that's a start: https://github.com/solana-labs/solana/blob/master/book/src/jsonrpc-api.md#getversion

But I feel like we can just generally be more fluid and adaptive. If an API call to another component fails, you always do what you can to recover and provide your caller with your best effort results. Even if all versions line up, any given API call may fail temporarily and we don't want to just blow up. Handling temporary network failures and other glitches cleanly seems to naturally allow us to use that same approach for version mismatches. That is supporting multiple versions of components officially is too soon, so any mismatch could be generically considered a temporary failure and/or standard input validation logic.

[sunnygleason]

@mvines right on, I'm on board with taming the cross-version compatibility matrix over time as opportunity allows. Here's a rough sketch of my understanding of what we're up against:

VERSIONS/RELEASES:
fullnode: [A1, A2, A3]
network-explorer-API: [B1, B2, B3]
network-explorer-webapp: [C1, C2, C3]

INTEROP:
1. "edge" -> "edge" : [A3, B3, C3] : easy, version 3 everywhere
2. "edge" -> "beta" : [A2, B2, C3] : C3 needs component fallbacks to legacy API B2
3. "edge" -> "stable" : [A1, B1, C3] : C3 needs component fallbacks to legacy API B1
4. "stable" -> "edge" : [A3, B3, C1] : B3 needs to provide legacy API B1 for desired components

Even if we add the constraint that "older" stages can't connect to "newer" stages, that only removes case 4 above. I don't see how we could have the constraint that "newer" stages can't connect to "older" stages (removing cases 2+3), that seems to be the whole point of the stage pipeline.

IMO we can handle all 4 cases in a manageable way, we just need to encapsulate the data requirements for each view and document the semantics of releases a bit better. We should be able to tackle that in an incremental way so it's not too burdensome.

(It also obviously won't impact fullnode dev velocity).

[mvines]

"edge" -> "edge" : [A3, B3, C3] : easy, version 3 everywhere

Not always! Fullnode on the edge testnet doesn't always restart on every single new commit into master.

The fallbacks really just need to be best effort. If it fails recover up as best you can and keep going. Normal input validation and clean error handling ought to get us close enough?