Guides

In this section we will try to introduce you to more in-depth look at Userfeeds Platform

API Authorization

APIs that write to Userfeeds Platform require Authorization header to be present with API key as a value.

Note

API key can be requested at https://api.userfeeds.io/portal/apis/, after registration. API key requests are currently approved manually so it may take up to 24h for you request to be approved.

Example of Authorized request would be:

cURL:

$ curl -X POST https://api.userfeeds.io/verify/ \
  -H "Content-Type: application/json" \
  -H "Authorization: YourAPIKey123" \
  --data @/path/to/claim.json

Python:

import json
import requests

claim = open('claim.json').read()
claim = json.loads(claim)

response = requests.post(
  "https://api.userfeeds.io/storage/",
  json=claim,
  headers={
      "Authorization": "YourAPIKey123"
  })

print(response.content)

Claims Signatures

Signed claims are created by adding special signature object to claim.

All claims inside Userfeeds Platform databases are signed (in some way). Claims sent to Userfeeds Platform through HTTP needs to be signed prior to being sent in contrast to claims sent via Ethereum transaction which signature is created on Userfeeds Platform side based on transaction containing the claim.

signature object structure inside claim looks like this:

{
  "context": "...",
  "claim": {
    "target": "..."
  },
  "signature": {
    "type": "TYPE",
    "creator": "CREATOR",
    "signatureValue": "SIGNATURES_VALUE"
  }
}

type

It descries what kind of signature we are dealing with.

Full list of supported types can be found at claim.signature.type reference.

creator

Identifier of entity that created the signature.

signatureValue

Signature allowing for verification that creator signed this claim.

Create signed Claim (ECDSA)

Following code will show you how to create signed claim with signature type of ecdsa.*.

Simple signing script written in Python.

import ecdsa
import json
import sys
import binascii
import hashlib

## Read claim from file
claim = open(sys.argv[-1]).read()
claim = json.loads(claim)

## Generate Keys
private_key = ecdsa.SigningKey.generate(curve=ecdsa.NIST256p)
public_key = private_key.get_verifying_key()

## Sign claim
message = json.dumps(claim, separators=(',', ':'), sort_keys=True).encode('utf8')

creator = public_key.to_string()
creator = binascii.hexlify(creator)
creator = creator.decode("utf8")

signature = private_key.sign(message, hashfunc=hashlib.sha256, sigencode=ecdsa.util.sigencode_der)
signature = binascii.hexlify(signature)
signature = signature.decode("utf8")

claim["signature"] = {
    "type": "ecdsa.prime256v1",
    "creator": creator,
    "signatureValue": signature
}

## Print signed claim
print(json.dumps(claim, separators=(',', ':'), sort_keys=True))

Save this code to sign.py and run it like this:

$ pip install ecdsa
$
$ python sign.py /path/to/claim.json

Simple signing script written in Javascript.

let KJUR = require('jsrsasign');
let serialize = require('canonical-json');
let fs = require('fs');

// Read claim from file
let claim = fs.readFileSync(process.argv[process.argv.length - 1]);
claim = JSON.parse(claim);

// Generate Keys
let curve = "secp256k1";
let keypair = KJUR.KEYUTIL.generateKeypair("EC", curve);
let sig = new KJUR.crypto.Signature({"alg": "SHA256withECDSA"});

// Sign claim
let message = serialize(claim);

let creator = keypair.pubKeyObj.pubKeyHex;

sig.init(keypair.prvKeyObj);
sig.updateString(message);
let signature = sig.sign();

claim. signature = {
  type: "ecdsa." + curve,
  creator: creator,
  signatureValue: signature
};

// Print signed claim
console.log(serialize(claim));

Save this code to sign.js and run it like this:

$ npm install canonical-json jsrsasign
$
$ node sign.js /path/to/claim.json

Verify claim signature

$ curl -X POST https://api.userfeeds.io/verify/ \
  -H "Content-Type: application/json" \
  -H "Authorization: API_KEY" \
  --data @/path/to/claim.json

Submiting claims

TODO

HTTP

TODO

Ethereum Transaction

TODO

Whisper message

TODO

Organic ranking with interface token

Warning

NOT IMPLEMENTED!

You can pass additional token to organic rankings to inject sponsored results into organic rankings. Those results will be marked with sponsored: true key in items list.

example:

GET /ranking/ORGANIC_TOKEN/SIMPLE_RANKING/?sponsored=INTERFACE_TOKEN

{
    "items": [
        {
            "value": "http://organic.com/art/1",
            "score": 1234
        },
        {
            "value": "http://organic.com/art/1",
            "score": 0,
            "sponsored": true
        },
        {
            "value": "http://organic.com/art/1",
            "score": 1100
        },
        ...
    ]
}

TODO…