86 lines
3.0 KiB
Markdown
86 lines
3.0 KiB
Markdown
# API
|
|
|
|
Here is an early overview of how to make API calls.
|
|
|
|
Implementation details for the **JSON-RPC** package are [here](https://github.com/filecoin-project/lotus/tree/master/lib/jsonrpc).
|
|
|
|
## Overview: How do you modify the config.toml to change the API endpoint?
|
|
|
|
API requests are made against `127.0.0.1:1234` unless you modify `.lotus/config.toml`.
|
|
|
|
Options:
|
|
|
|
- `http://[api:port]/rpc/v0` - HTTP endpoint
|
|
- `ws://[api:port]/rpc/v0` - Websocket endpoint
|
|
- `PUT http://[api:port]/rest/v0/import` - File import, it requires write permissions.
|
|
|
|
## What methods can I use?
|
|
|
|
For now, you can look into different files to find methods available to you based on your needs:
|
|
|
|
- [Both Lotus node + storage miner APIs](https://github.com/filecoin-project/lotus/blob/master/api/api_common.go)
|
|
- [Lotus node API](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go)
|
|
- [Storage miner API](https://github.com/filecoin-project/lotus/blob/master/api/api_storage.go)
|
|
|
|
The necessary permissions for each are in [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go).
|
|
|
|
## How do I make an API request?
|
|
|
|
To demonstrate making an API request, we will take the method `ChainHead` from [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go).
|
|
|
|
```go
|
|
ChainHead(context.Context) (*types.TipSet, error)
|
|
```
|
|
|
|
And create a CURL command. In this command, `ChainHead` is included as `{ "method": "Filecoin.ChainHead" }`:
|
|
|
|
```sh
|
|
curl -X POST \
|
|
-H "Content-Type: application/json" \
|
|
--data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 3 }' \
|
|
'http://127.0.0.1:1234/rpc/v0'
|
|
```
|
|
|
|
If the request requires authorization, add an authorization header:
|
|
|
|
```sh
|
|
curl -X POST \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer $(cat ~/.lotusstorage/token)" \
|
|
--data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 3 }' \
|
|
'http://127.0.0.1:1234/rpc/v0'
|
|
```
|
|
|
|
> In the future we will add a playground to make it easier to build and experiment with API requests.
|
|
|
|
## CURL authorization
|
|
|
|
To authorize your request, you will need to include the **JWT** in a HTTP header, for example:
|
|
|
|
```sh
|
|
-H "Authorization: Bearer $(cat ~/.lotusstorage/token)"
|
|
```
|
|
|
|
Admin token is stored in `~/.lotus/token` for the **Lotus Node** or `~/.lotusstorage/token` for the **Lotus Storage Miner**.
|
|
|
|
## How do I generate a token?
|
|
|
|
To generate a JWT with custom permissions, use this command:
|
|
|
|
```sh
|
|
# Lotus Node
|
|
lotus auth create-token --perm admin
|
|
|
|
# Lotus Storage Miner
|
|
lotus-storage-miner auth create-token --perm admin
|
|
```
|
|
|
|
## What authorization level should I use?
|
|
|
|
When viewing [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go), you will encounter these types:
|
|
|
|
- `read` - Read node state, no private data.
|
|
- `write` - Write to local store / chain, and `read` permissions.
|
|
- `sign` - Use private keys stored in wallet for signing, `read` and `write` permissions.
|
|
- `admin` - Manage permissions, `read`, `write`, and `sign` permissions.
|