REST API Proposal

Proposed Blockchain REpresentational State Transfer (REST) Application Programming Interface (API)

Requirements

1. Make a localized blockchain REST API

Postman Collection for Testing

Postman is a valuable HTTP request testing GUI application that makes sending requests fun! Here is a collection of requests specifically for the Essential Blockchain for quick and dirty testing.

Naming Conventions within this Document

Domain	Example
Java	ClassName.java
REST	/resource or /parent/{parentIdPlacehodler}/child

Term	Meaning
Client	The developers using this blockchain REST API
Server	The server to which the developers are sending and receiving requests

Table of methods, resources and responses

HTTP Method	REST Verb	Path	Body	Response	Description
POST	CREATE	/blockchain		The id of the created blockchain.	Creates a blockchain and returns its id.
GET	GET	/blockchain/{id}		The entire contents of the requested blockchain.	Gets the contents of a blockchain.
GET	GET	`/blockchain/{id}/buffer		The transaction buffer on the server.	Gets the transaction buffer from the server.
DELETE	DELETE	`/blockchain/{id}/buffer		204 empty response if successful.	Clears the transaction buffer of transactions without performing mining (effectively deleting all the transactions within that buffer).
POST	MINE	/blockchain/{id}		The contents of the newly mined blockchain.	Requests the server empty its buffer of transactions into a new block and mine that block, then return its contents.
POST	CREATE	/blockchain/{bcId}/transaction	{ "payload": <String> }	The created transaction.	Adds the requested transaction to the server's transaction buffer. Occasionally this method will cause the buffer to fill up, at which point the most recently buffered transaction will be stored into a block, have that block be mined and added to the blockchain.
GET	GET	/blockchain/{bcId}/transaction/{txId}		The requested transaction.	Requests the server search through all blocks to find the transaction with the given id.
GET	GET	/blockchain/{bcId}/block/{bId}/transaction/{txId}		The requested transaction.	Requests the server search the given block's transaction for a transaction with the given id.

Error Structure

All errors have the same structure, and provide both a userMessage and a developerMessage, which the client can use to display to the client directly into a GUI and help debug a test session respectively.

Field	Example Value	Description
"status"	400	The HTTP status code of the error. Usually it will be either a 4xx or 5xx in accordance with standard HTTP specs.
"message"	"BAD_REQUEST"	The HTTP status message associated with the error, in UPPER_SNAKE_CASE.
developerMessage	"The requested transaction with id 1 cannot be found. Exception: No value present"	A developer-friendly message that describes the technical details of the problem and includes the message of whatever exception was thrown at the end.
userMessage	"We couldn't find a transaction with an id matching 1."	A user-friendly message that describes the problem in a general sense. This text is meant to be directly displayed ina user interface in an application.

Problems

• We need some way for a client to know if the transactions they've POSTed to a given blockchain are actually a part of a mined (and therefore verified) block in that blockchain.
  • In the Java API a Transaction.java does not know about the block to which is belongs. But, perhaps it is useful for the REST resource /transaction to contain at least a boolean isValidated or even a reference to the /block to which it belongs, so tha
• How to handle "transaction buffering" on the server
  1. Always have the server wait until it has enough transactions to fulfil the maxBlockSize to start mining a new block (and eventually add it).
  2. Always have the server wait like above, except after a certain arbitrary time limit specified at blockchain creation, e.g. 2 hrs after the last transaction received.
  3. Require a client to call a specific REST verb, e.g. MINE, to force the server to create, mine and append to a given blockchain a block. This block is constructed out of whichever transactions it has not yet accumulated into a mined block.
• The degree to which this API should expose implementation details (such as Merkle Trees), which might be useful for teaching about blockchain technologies in demo applications, but would violate encapsulation in production applications.

Future Considerations

• How to query the blockchain
• Distributed consensus