server

README

go-http-api

A package that provides an HTTP REST API for a Filecoin implementation written in go.

Features

• Response body is JSON.
• POST request bodies are expected to be JSON.
• SSL/TLS supported
• Bearer auth scheme supported (SOON)

Install

go get github.com/filecoin-project/go-http-api

Implement

1. Set up vN.Callbacks

The core of the API is the Callbacks struct. It is a typestruct in each API version package containing named callback functions, which should call into your code. The server is then instantiated with your desired callbacks. Each version of the API has its own Callbacks struct:

package v1
import(...)
type Callbacks struct {
	GetActorByID func(string) (*types.Actor, error)
	GetActorNonce func(string) (*big.Int, error)
	GetActors func() ([]*types.Actor, error)
    // ... etc
}

Because it is a struct and not an interface, implementers are free to support as much of the API as they like; a default handler will be used for nil Callbacks in each, for example:

curl http://localhost:5000/api/filecoin/v1/actors
    /api/filecoin/v1/actors is not implemented

A 404 response will be sent for endpoints that don't (and can't) exist:

curl http://localhost:5000/api/filecoin/v1/atcorz
    curl: (22) The requested URL returned error: 404 Not Found

This standardizes unimplemented endpoint responses for every node, ensures the API endpoints are compliant with the API spec, and more easily allows the API consumer to know what functionality is implemented -- or at least, what is exposed to the API -- by each node.

The design also allows one to implement a proxy server that can communicate via its backend with a Filecoin cluster (if there are separate nodes for storage, retrieval, payments, proofs, mining, etc.) controlled by one operator, thus providing a single, externally accessible endpoint. Potential use cases include exchanges, block explorers, node control, or storage management.

It is expected for this API to be useful for building a Filecoin implementation's command line interface.

In order to be implementation-agnostic, this package uses its own Filecoin-based typestructs for callbacks and serialized responses.

2. Instantiate and run the server

Place the following code somewhere in your node startup sequence:

cb := &v1.Callbacks {
    GetActorByID: cbs.MyGetActorByIDFunc,
    GetActorNonce: cbs.MyGetActorNonceFunc,
    // ...
    SendSignedMessage: cbs.MySendSignedMessageFunc,
    WaitForMessage: cbs.MyWaitForMessageFunc,
}

cfg := server.Config{
    Port: 5001,
    TLSCertPath os.Getenv("TLS_CERT_PATH")
    TLSKeyPath  os.Getenv("TLS_KEY_PATH")
}

s := server.NewHTTPAPI(context.Background(), cb, cfg).Run()

3. Launch your node and test the endpoints

First launch your filecoin node. Then, to verify only that you have correctly launched the HTTP API server, use the hello endpoint:

curl http://localhost:5000/api/filecoin/v1/hello
    HELLO

Then attempt to retrieve information from your node, by sending a request to an endpoint for one of the callbacks you implemented:

curl http://localhost:5000/api/filecoin/v1/actors

Assuming you have correctly implemented your callbacks, you should see familiar output.

Please see test files for more details.

References

• For a current map of endpoints to callbacks, see server.Route()
• Filecoin HTTP API Specification
• filecoin-project/go-filecoin example implementation in a branch

Contributing

We ❤️ all our contributors; this project wouldn’t be what it is without you! If you want to help out, please see CONTRIBUTING.md.

License

The Filecoin Project, including this repository, is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Copyright

Documentation

Index

• Constants
• type Config
• type HTTPAPI
  • func NewHTTPAPI(ctx context.Context, cb1 *v1.Callbacks, config Config) *HTTPAPI
  • func (s *HTTPAPI) Config() Config
  • func (s *HTTPAPI) Route()
  • func (s *HTTPAPI) Router() chi.Router
  • func (s *HTTPAPI) Run() *HTTPAPI
  • func (s *HTTPAPI) Shutdown() error

Constants

const DefaultPort = ":8080"

DefaultPort is the default port for the REST HTTP API

Types

type Config

type Config struct {
	Port        int
	TLSCertPath string
	TLSKeyPath  string
}

Config is implementation-specific configuration for the API

type HTTPAPI

type HTTPAPI struct {
	// contains filtered or unexported fields
}

HTTPAPI is a struct containing all the things needed to serve the Filecoin HTTP API

func NewHTTPAPI

func NewHTTPAPI(ctx context.Context, cb1 *v1.Callbacks, config Config) *HTTPAPI

NewHTTPAPI creates and returns a *HTTPAPI using the provided context, *Callbacks, and desired port. If port <= 0, port 8080 will be used.

func (*HTTPAPI) Config

func (s *HTTPAPI) Config() Config

Config returns a copy of the config

func (*HTTPAPI) Route

func (s *HTTPAPI) Route()

Route sets up all the routes for the API

func (*HTTPAPI) Router

func (s *HTTPAPI) Router() chi.Router

Router returns the chimux router. Currently used for testing (see server_test)

func (*HTTPAPI) Run

func (s *HTTPAPI) Run() *HTTPAPI

Run sets up the route handlers using the provided callbacks, and starts the HTTP API server.

func (*HTTPAPI) Shutdown

func (s *HTTPAPI) Shutdown() error

Shutdown shuts down the http.Server.