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