Design REST APIs Definition

[bipinkh]

API design specification and implementation by the node.

Endpoints will include :

• Idea CRUD (by any user)
• Validator CRUD (by OSO network)
• Submit or update metadata, and update torrent files.
• Select a processor for the Idea (by author)
• Supporting endpoints for Validators
  • Sign/Validate the Idea
  • Assign validation responsibility to other Validators
• Search the contents based on metadata
  • Local search
  • Search with other clients/nodes

Endpoints relating to citations and token distribution is not considered in this Issue.

[bipinkh]

Download all the endpoints described in the below comments as a file here :
IdeaHub_RestApi_Specs-v1.0.pdf

[bipinkh]

Authentication and Request validation

The REST API below ignores the request or session validation of the user. Each request will have a header that consists the identifier (public key or any other id) of the requestor and a signature of the request body, request params and nonce combined. This way, the requestor can be identified and the request made by the requestor can be verified.

Algorithm for authentication and signature validation is not yet finalized.

[bipinkh]

User Onboarding

Based on the Proof of Idea there are 2 proposed options for user registration: "Verification by a subset of total users" and "Anyone can join" schemes.

The necessary attributes of any user required during registration is a matter of discussion. How will the user verify the new user? The use of public key is not enough and a new way of user-friendly approach is required.

The API has been put on hold until this discussion.

[bipinkh]

Idea CRUD

Idea DTO

idea_dto:
{
	"id": string, // can be uuid or the hash of all metadata
	"type": string,
	"title": string,
	"abstract": string,
	"doi": string,
	"date": date,
	"categories": string[],
	"authors": string[],
	"file": string
}

param	description	example
type	type of the article: paper, presentation, article, book	"paper"
title	title of the idea	"Proof of Idea: OSO"
abstract	abstract of the idea
doi	document identifier
date	published or released date	2020-06-18
categories	idea category	["p2p", "ethereum"]
authors	name of the author. However, we can keep it as an object or stringified json consisting name, public key and other meta information about the authors. This can be useful in filtering the ideas by a particular author.	["G.J. Katuwal"]

Post new idea

• accessible to [ user ]

Any registered user can post the idea. The request body parameters is considered in reference with ResearchGate submission form.

POST /api/v1/ideas

Request Body: idea_dto excluding the uuid field

Response Body: idea_dto

Update the idea

• accessible to [ user ]

After the update is made to the previously posted idea, there might be a requirement to re-validate this idea by the validators.

PATCH /api/v1/ideas/{id}

{
	"type": string,
	"title": string,
	"abstract": string,
	"doi": string,
	"date": date,
	"categories": string[],
	"authors": string[],
	"file": string
}

Request Body: idea_dto excluding the uuid field

Response Body: idea_dto

Path variable 'id' refers to the id of the idea being updated

Remove idea

• accessible to [ idea owner, oso ]

DELETE /api/v1/ideas/{id}

Read the details of the idea

• accessible to [user]

This is similar to reading the metadata of the idea. It is not the endpoint to download the file. The metadata can contain the torrent link or any other download link of the file.

GET /api/v1/ideas/{id}

Request Body: idea_dto

[bipinkh]

Validators CRUD

Validator is added or removed by the OSO network

DTO

validator_dto:
{
	"id": string, 
	"since": date,
	"active": boolean,
	"available": boolean
}

param	description	example
id	user identifier	"0x111111111111111"
since	date since which this node is assigned as a validator	2020-01-01
active	true if the validator is active false if the validator is blocked, disabled or removed	true
available	Voluntary declaration by the validator itself regarding its availability true if the validator is currently accepting to validate ideas false if validator is not available to accept ideas	true

Create

• accessible to [oso]

POST /api/v1/validators

{
	"id": string // user identifier
}

Response: validator dto

Update

• accessible to [oso]

PUT /api/v1/validators/{id}

{
	"active": boolean
}

Response: validator dto

• accessible to [validator]

PUT /api/v1/validators/{id}

{
	"available": boolean
}

Response: validator dto

Remove

• accessible to [oso, validator]

DELETE /api/v1/validators/{id}

Get

• accessible to [user]

GET /api/v1/validators

Request param	Description	Default
id	[optional] validator id	null
page	[optional] page number	1
size	[optional] number of validator list per page	25

Response: list of validator dto

When the request param id is provided, the response list contains just a single DTO of the validator with given id.

[bipinkh]

Idea Validation

The node that processes the idea creation request of a network can assign the idea to a group of validators. The assignment can be done autonomously using a algorithm that allows fair distribution of validation responsibility to the validators.

DTO

validation_dto:
{
	"id": string,			
	"idea": string,			
        "validator": string,	
	"assigned_on": datetime,
	"deadline": datetime,	
	"validated_on": datetime, 
	"status": string,		// "inprogress", "denied", "completed", "revoked" 
	"remarks": string,		// reason if denied or rejected
	"sign": string			// signature of validator
}

Request Body Param	Description	Example
id	validation identifier	23L
idea	idea identifier	jsnkasnfksmfalf
validator	validator identifier	anfamflasmdads
assigned_on	date time on which the validation was assigned	2020-01-01T15:23:232
deadline	date time on which the validation has to be completed	2020-01-10T23:23:22:232
validated_on	date time on which validator completed the process	2020-01-04T00:00:00:000
status	enum: inprogress - validation is in progress denied - validator denied to validate this idea validated - validator has validated successfuly rejected - validator has invalidated the idea revoked - OSO has revoked the validation authority to this validator because of its misbehavior, for re-assignment or due to deadline constraint	inprogress
remarks	include message of denial, rejection or any related information	"Categories does not match"
sign	signature of the validator

Assign idea validation task to a validator

• accessible to [oso]

POST /api/v1/validations

{
	"idea": string, // idea identifier
	"validator": string // validator identifier
	"deadline": date	// date by which the validation has to be completed
}

Response: validation dto

Revoke validation of an idea for any validator

• accessible to [oso]

DELETE /api/v1/validations/{id}

Response: validation dto

The status field will change to "revoked"

Validation update

• accessible to [validator]

Validator can deny the validation. Or, respond with validation successful or rejection status along with its signature.

PUT /api/v1/validations/{id}
{
	"status": string,
	"remarks": string,
	"sign": string
}

Response: validation dto

[bipinkh]

Search

Search by meta information

• for "user to node" or "node to node"

GET /api/v1/search	

Optional Request param	Data Type	Description	Example
author	string[]	list of authors	["G.J. Katuwal", "S. Pandey"]
doi	string	document identifier	"10.12121/RG.2.2.1.1"
from	date	published date range from	"2020-01-20"
to	date	published date range to	"2020-05-05"
title	string	idea title	"Decentralized Cloud Storage"
categories	string[]	categories	["p2p", "cloud-storage"]
type	string[]	idea type	["paper", "article", "presentation"]
abstract	string[]	keywords to be included in abstract	["blockchain", "proof of idea", "convolutional neural network"]
page	int	page number [optional] default: 1	1
size	int	page size [optional] default: 25	25

Response: List of idea dto