NeoFS REST Gateway

Neo SPCC
3 min readOct 4, 2022

--

NeoFS becomes more friendly for web application developers.

Modern apps and dApps are mostly web oriented. Web applications provide the same user experience for users across various platforms. At NSPCC, we have always wanted to give web developers the full powers of NeoFS and its native API. However, to achieve this we had to face some challenges.

  1. NeoFS API is a binary protocol with protobuf declaration, which is not quite suitable for web applications.
  2. NeoFS API does not support a de facto standard mechanism of signing data in web applications using Wallet Connect.

After long discussions and experiments, NeoFS API started to support Wallet Connect signature scheme. The latest neofs-node versions already implement that. So, this opens all doors for the new NeoFS REST Gateway.

Try NeoFS REST Gateway

Important! This is the first version of REST Gateway and it contains many sharp edges and areas for improvement. We want to make it useful for all kinds of developers, so don’t hesitate to suggest features or leave feedback on issues page. Thank you!

REST Gateway is available as a binary, docker image, and a part of NeoFS All-In-One environment for local tests. To start, specify NeoFS Node endpoint (find public NeoFS endpoints at https://status.fs.neo.org). API will be available at http://127.0.0.1:8080/v1.

$ ./bin/neofs-rest-gw -p grpcs://st1.t5.fs.neo.org:8082
info neofs-rest-gw/config.go:195 no wallet path specified, creating ephemeral key automatically for this run
info neofs-rest-gw/config.go:379 added connection peer {"address": "grpcs://st1.t5.fs.neo.org:8082", "priority": 1, "weight": 1}
info metrics/service.go:33 service hasn't started since it's disabled {"service": "Pprof"}
info metrics/service.go:33 service hasn't started since it's disabled {"service": "Prometheus"}
Serving neofs rest gw at http://127.0.0.1:8080

REST Gateway uses Open API 2.0 specification, see spec/rest.yaml file. Find autogenerated docs at http://127.0.0.1:8080/v1/docs, and more NeoFS-specific documentation at http://127.0.0.1:8080/docs.

Why not NeoFS HTTP Gateway

Adding a control panel made us rethink the way the gateway works with requests, its parameters, and headers. While HTTP Gateway works with binary encoded structures, we wanted to provide a better experience for web developers with human-readable JSON structures in request bodies and responses.

To avoid mixing these approaches, we decided to keep HTTP Gateway as a simple, reliable, and blazingly fast data access point for NeoFS. This is the core of our incoming CDN service. You don’t have to choose one gateway implementation over another. It’s better to use both wisely.

REST Gateway application demo

Soon we are going to publish Panel.NeoFS — our web application to control NeoFS assets directly from your browser just with your wallet. It uses all features of REST Gateway and serves as a great example of the capabilities open for developers. Now look at the sneak peek of what is possible with the new REST Gateway

--

--