Documentation

“The Things which hurt, instruct.” ― Benjamin Franklin

Introduction

Wisdom runs a proxy service which adds micropayment invoicing and authentication to any API. Powered by NGINX and Google's cloud infrastructure, requests proxied by Wisdom's service will be capable of carrying identity and payments on invoicing channels powered by the Lightning Network. Wisdom will support both Bitcoin and Litecoin for invoicing and payments.

Wisdom's core features also include providing secure and reliable API user credential storage and content hosting services via the IPFS network.

Features

Wisdom's APIs currently support the following features:

  • Adding new remote (3rd party) API endpoints to the proxy
  • Proxying secure calls to remote API endpoints
  • Providing statistics for calls to those remote APIs
  • Proxying secure calls to the IPFS network (acting as a gateway)
  • Adding new objects to Wisdom's IPFS node Invoiced Feature
  • Pinning objects uploaded to the IPFS network Invoiced Feature
  • Advertising objects to pin on the IPFS network Invoiced Feature

Keep a close eye out for the addition of invoices to the APIs in the near future.

Visit our Gitter if you need any help!

Service APIs

Wisdom's service APIs may or may not require a payment invoice to make a call. Service APIs live under the following URI, which is running TLS:

https://api.wisdom.sh/api/

Service Status

To get started with our APIs, issue a GET request to api.wisdom.sh for the /api/status endpoint in your bash terminal. A JSON formatted response giving system status is returned:

GET /api/status
curl https://api.wisdom.sh/api/status

{ 
 "response": "success", 
 "message": "Service is up.",
 "view": "https://wisdom.sh/status",
 "timestamp": 1506816332079
} 

Adding APIs

Wisdom proxies API endpoints which are added to the system by users. To add an API to the system, create a POST request, including the key values name, upstream_url and uri to map onto the //api.wisdom.sh/ namespace.

POST /api/
curl -X POST \
  --url https://api.wisdom.sh/api/ \
  --data 'name=eurorates' \
  --data 'upstream_url=https://api.fixer.io/latest' \
  --data 'uris=/eurorates' \
  | python -m json.tool

{
    "created_at": 1504898023474,
    "http_if_terminated": false,
    "https_only": false,
    "id": "a8d02990-01e6-4f6a-b5ed-48ad8a542d7f",
    "name": "eurorates",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "https://api.fixer.io/latest",
    "uris": [
        "/eurorates"
    ]
}

Authentication

Service endpoints on the /api/ path do not require authentication. However, some endpoints may require invoices depending on demand for a given API resource. Endpoints on paths outside the /api/ service may require authentication or invoices.

API Proxy

In addition to its own service endpoints, Wisdom's API proxy includes third party endpoints which have been added to the system. These proxied APIs are accessed using the following URL structure:

https://api.wisdom.sh/<api_name>

Requesting 3rd Party APIs

The example below shows using a GET request to access the /eurorates endpoint. The request is proxied by Wisdom which returns the default JSON response from the /latest path on the fixer.io API:

GET //api.wisdom.sh/eurorates
curl https://api.wisdom.sh/eurorates | python -m json.tool

{
    "base": "EUR",
    "date": "2017-09-08",
    "rates": {
        "AUD": 1.4881,
        "BGN": 1.9558,
        "BRL": 3.7256,
        ...
        "TRY": 4.1191,
        "USD": 1.206,
        "ZAR": 15.512
    }
}

API Details

Use a GET request against the /api/ service path to request known details about the third party API and the proxy serving it:

GET /api/<api_name>/
curl https://api.wisdom.sh/api/eurorates/ | python -m json.tool

{
    "created_at": 1504898023474,
    "http_if_terminated": false,
    "https_only": false,
    "id": "a8d02990-01e6-4f6a-b5ed-48ad8a542d7f",
    "name": "eurorates",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "https://api.fixer.io/latest",
    "uris": [
        "/eurorates"
    ]
}

Versioning

Versioning of APIs will be addressed in the near future.

IPFS Proxy

Wisdom runs an SSL'd IPFS gateway. The IPFS gateway enaables browsing hashed or named objects stored on the IPFS network using an unmodified Web client. Access to the IPFS newtork gate is done via the following URIs:

https://ipfs.wisdom.sh/ipfs|ipns/

IPFS Gateway Status

The status of Wisdom's IPFS gateway may be queried using a GET request on the api.wisdom.sh hostname:

GET https://api.wisdom.sh/ipfs/status
curl https://api.wisdom.sh/ipfs/status

{ 
 "response": "success", 
 "message": "Service is up.",
 "view": "https://wisdom.sh/status",
 "timestamp": 1506816332079
}

Requesting IPFS Objects

IPFS objects may be requested from Wisdom's IPFS gateway using a GET request to the ipfs.wisdom.sh hostname:

GET https://ipfs.wisdom.sh/ipfs/<hash>/<object>
curl https://ipfs.wisdom.sh/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme

Hello and Welcome to IPFS!

██╗██████╗ ███████╗███████╗
██║██╔══██╗██╔════╝██╔════╝
██║██████╔╝█████╗  ███████╗
██║██╔═══╝ ██╔══╝  ╚════██║
██║██║     ██║     ███████║
╚═╝╚═╝     ╚═╝     ╚══════╝

If you're seeing this, you have successfully installed
IPFS and are now interfacing with the ipfs merkledag!

 -------------------------------------------------------
| Warning:                                              |
|   This is alpha software. Use at your own discretion! |
|   Much is missing or lacking polish. There are bugs.  |
|   Not yet secure. Read the security notes for more.   |
 -------------------------------------------------------

Check out some of the other files in this directory:

  ./about
  ./help
  ./quick-start     <-- usage examples
  ./readme          <-- this file
  ./security-notes

Adding IPFS Objects Invoiced Feature

IPFS objects may be added to Wisdom's IPFS node by using a POST request to the /ipfs/ endpoint on the api.wisdom.sh hostname:

POST https://api.wisdom.sh/ipfs/
curl -X POST \
  --url https://api.wisdom.sh/ipfs/ \
  --data 
  | python -m json.tool

{
    "created_at": 1504898023474,
    "http_if_terminated": false,
    "https_only": false,
    "id": "a8d02990-01e6-4f6a-b5ed-48ad8a542d7f",
    "name": "eurorates",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "https://api.fixer.io/latest",
    "uris": [
        "/eurorates"
    ]
}

Pinning IPFS Objects Invoiced Feature

IPFS objects on the IPFS network may be pinned to Wisdom's IPFS nodes. To request an object be pinned by Wisdom's nodes, create a new payment invoice by doing a POST request to the /ipfs/pin endpoint on the api.wisdom.sh hostname:

POST https://api.wisdom.sh/ipfs/pin
curl -X POST \
  --hash xxxxxx  \
  --data 
  | python -m json.tool

{
    "created_at": 1504898023474,
    "http_if_terminated": false,
    "https_only": false,
    "id": "a8d02990-01e6-4f6a-b5ed-48ad8a542d7f",
}
        

Advertising IPFS Objects Invoiced Feature

IPFS objects on the IPFS network may be advertised to be pinned by other IPFS nodes. To advertise an object to be pinned, create a new advertisment by doing a POST request to the /ipfs/advertise endpoint on the api.wisdom.sh hostname:

POST https://api.wisdom.sh/ipfs/advertise
curl -X POST \
  --hash xxxxxx  \
  --data 
  | python -m json.tool

{
    "created_at": 1504898023474,
    "http_if_terminated": false,
    "https_only": false,
    "id": "a8d02990-01e6-4f6a-b5ed-48ad8a542d7f",
}