API / debugAPI design

[Eknir]

Right now, API is:

• Mature features which are user-facing
• They are not meant to expose the user to danger when exposed to the internet, but if we go live on mainnet, then upload/download API endpoints should be guarded

Right now, debugAPI is:

1. bee operator endpoint (get status of current bee node)
2. experimental and/or deprecated features
3. endpoints which we don't want to expose via API due to security reasons

Some features which are exposed from the debugAPI need to be exposed to developers to interact with the bee node from the browser (e.g. bee-status. @alsakhaev requested CORS on the debugAPI (#1280)

All together, the situation calls for an analysis for the different API routers we expose, their functionality and their protection.

[significance]

sweet 🤙 can we generalise this to include also the api and gateway mode?

[significance]

guys here are some sketch user roles i made a while ago.

there are a lot of ways to cut it but i think these are quite distinct and easy to reason with.

1. I am an infrastructure node operator using Bee to earn BZZ using my available resources.
2. I am a mobile/desktop app user using a local Bee proxy to provide ‘back end’ functionality of my app.
3. I am a web app user using a Bee gateway as the ‘back end’ functionality of my app.
4. I am a gateway operator providing Bee gateway services to web app users.
5. I am a developer of 1,2,3 or 4

[agazso]

I think the 3 points by @Eknir describe well the current situation and I can easily image that they provide a way to move forward.

1. The developer endpoints may only contain features that are used to help the development of Bee in some ways (e.g. testing). Normal users should not have it enabled and it should be difficult to enable CORS for these endpoints because they are potentially dangerous or destructive. No experimental or deprecated features belong here. This could be on a different port (e.g. 1635) and by default only exposed on localhost.

2. Experimental and deprecated features could be enabled on the normal API (e.g. 1633) but they could be enabled conditionally, for example by providing a command-line option.

3. All other endpoints could be exposed on the normal API but there could be "private" endpoints which require some form of authentication (e.g. an API key) to be accessed. One could also argue that actually all endpoints are such endpoints, because potentially all exposed operations (will) cost money at some point.

[vojtechsimetka]

Two API requests:

• expose Ethereum network & chain ID Identify ethereum network connection to user bee-dashboard#6
• health endpoints on both API and debug API ideally as websockets Health of API and debug API should be websocket connection bee-dashboard#17

[Eknir]

I spoke about this with Janos, and we concluded the following:

1. The API and debugAPI were designed in a specific way. I don't see a reason to get rid of this design at this point. debugAPI is intended for node operators, to inspect the status of their node. api is used by dapps, to interact with the Swarm network. @janos can explain the vision much better than I do here. We agreed that he will update the documentation. @janos , will you leave a comment here when this PR is out?

2. we need to change the name of API and debugAPI, as it is confusing and doesn't tell anything to the user. I suggest to change debugAPItonetworkanddebugAPItonode` (@janos, this is different than what we spoke about in our call, but I gave it some thought and would suggest the above. Let me know what you think).

3. the gateway-mode is not documented, neither in our docs, nor in our API documentation. I will make an issue (and link it here shortly), which requests this documentation.

Responding to @agazso :

1: there is currently only one such 'developer' endpoint (/chunk/delete). I agree about moving this away from the debugAPI, as this is not an operation which we want any user to do under normal circumstances. I asked @janos how/where this is currently used. With regards to testing, the vision of @janos is that integration tests should only mimick "normal" operators, and hence these 'developer' endpoints are not explicitly needed. Nevertheless, I can imagine the functionality of such endpoints for testing or research, and I would support creating a separate endpoint for this.

2: Good suggestion. There are currently no experimental and deprecated features. Will keep your suggestion in mind for the future.

3: We spoke about this with @janos and agreed that there is no fundamental difference between "normal" websites (which can incur bandwidth that costs/costed money) and web3 endpoints. Nevertheless, I sympathize with you here, as it might be better to be cautiousness than reckless in the beginning. @janos , wdyt about making all API endpoints protected by some authentication?

[Eknir]

document gateway-mode issue: ethersphere/bee-docs#163

[agazso]

3: We spoke about this with @janos and agreed that there is no fundamental difference between "normal" websites (which can incur bandwidth that costs/costed money) and web3 endpoints. Nevertheless, I sympathize with you here, as it might be better to be cautiousness than reckless in the beginning. @janos , wdyt about making all API endpoints protected by some authentication?

To me it seems that there is a difference between certain endpoints. Otherwise why are they disabled in gateway mode?

[acud]

We are actively researching the permissioned API topic. I'm closing this in the meanwhile as some more ripe conclusions should emerge out of that very soon. A possible coalescing of both API is in the cards with role based APIs