distributive-network / dcp-rest

A Restful HTTP server wrapper for common dcp-client operations

Restful DCP (dcp-rest)

A Restful HTTP API wrapper for common dcp-client operations.

This is a flexible api that will allow you to manage jobs deployed from bifrost or dcp-client as well as provide a rich experience for deploying jobs itself.

Endpoints

Deploying a Job to dcp

Deploy jobs to DCP. Full language support with libraries for Python and R is coming soon. Path: /job Method: POST

Example request body:

{
	"slices": [1,2,3,4,5,6,7,8,9,10],
	"work": {
		"language": "js",
		"function": "(datum) => { return datum * 2; }"
	},
	"account": {
		"address": "94E619279C5780fF20ECe07fAA719e3D66111A88"
	}
}

Upload data for your Job to work on

In dcp-rest, every job is an "open job", which means you can add slices to be computed anytime after deploying - in fact, you can even omit the slices property of the request body in the example above and opt to add them later or in batches if you prefer.

Path: /job/{jobId}/slices Method: POST

Getting results

Download your currently computed results. Path: /job/[id]/result Method: GET

Example request:

/api/v0/job/$JOBID/result?range=1-10&range=33-35

^ Will return the results for slices 1 to 10 and 33 to 35

Example Postman request:

Job Status

Path: /job/[id]/status Method: GET

Forcefully kill a running Job

Stop a job from completing mid execution. Path: /job/{jobId} Method: DELETE

List your bank keystores on DCP

List the bank accounts associated with your identity. Path: /accounts Method: GET

Auth

dcp-rest uses two types of authorization and authentication:

1. Bearer token API keys (not yet implemented)
2. Basic tokens comprising of an id keystore and id keystore password

Basic Auth

Note: in order to get the best experience with dcp-rest, please use an identity keystore which is a proxy to your DCP portal account. This is not required for most of the endpoints, but is used for deploying jobs and listing user bank accounts. <TODO: make a website that generates them and link it here>

Here is an example of generating a token in JavaScript:

const idKeystore = wallet.getId();
const idKeystoreJSON = `${JSON.stringify(idKeystore.toJSON())}`;
const idKeystorePass = 'myepicpassw0rd'

const token = `Basic ${btoa(idKeystoreJSON + ':' + idKeystorePass)}`;

Important Note: DCP does not have a solid "identity"/"auth" underlying implementation yet (but will sometime soon). This means you must use the exact same id keystore to manage a job as you did to deploy it.

Try it out!

docker build -t dcp-rest .
docker run -p 1234:1234 dcp-rest

Roadmap

Primary items on the roadmap

• add better examples
• create an oauth app for api key generation
• add better error handling and error responses
• add support for Python and R in work functions (Python will be easy / might work already)
• ci

dcp-rest's Issues

Update protocol requests to work with new protocol api

Refer to DCP MR !2457 for examples of new api and consult with Yarn

Change `work.language` to an API more suitable with dcp Worktimes

work.language is a simpler version of the new DCP Worktimes feature going into DCP soon. The API for deploying a job should change so that the worktime can be specified.

Pick bank account by label name instead of address

Portal bank accounts are guaranteed to have a unique name,

well, there are some accounts which have multiple accounts with the same name, and technically you can create multiple accounts with the same name as theres no restriction on the backend, but we block the ability to create multiple bank accounts with the same name on the frontend and expect accounts to have a unique name

so we should allow the user to choose a bank account by its name "label" instead of account address. This is simpler and more congruent with the wallet api