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
Sponsored vs Organic Rankings¶
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…