gradido/docu/community-server.api.md

Community Server API

This document describes the community server API. The community server is written in PHP and mixes front with backend. Furthermore cakePHP and its auto-generated controller structure is used to access the API. This whole part of the Software will be subject to refactoring.

// TODO In this examples I assume that you use gradido with or docker-compose build on your local maschine

Error handling

// TODO

Account overview

Returns the current account balance

Request

GET http://localhost/state-balances/ajaxGetBalance/-127182

Response

Assuming: session is valid

{
	"state":"success",
	"balance":174500 
}

• balance: balance describes gradido cents which are 4 digits behind the separator. A balance value of 174500 equals therefor 17,45 GDD

List transactions

List all transactions for logged in user

Request

GET http://localhost/state-balances/ajaxListTransactions/-127182/[DESC] (The DESC part is optional symbolized by [])

Response

Assuming: session is valid

{
	"state":"success",
	"transactions": [
		{
			"name": "Max Mustermann",
			"email": "Maxim Mustermann", 
			"type": "send",
			"transaction_id": 2,
			"date": "2021-02-19T13:25:36+00:00",
			"balance": 1920000,
			"memo": "a piece of cake :)",
			"pubkey": "038a6f93270dc57b91d76bf110ad3863fcb7d1b08e7692e793fcdb4467e5b6a7"
		 }
	],
	"transactionExecutingCount": 0,
	"count": 1,
	"gdtSum": 0,
	"timeUsed": 0.04562687873840332
}

• transactionExecutingCount: how many transaction for this user currently pending and waiting for signing
• count: sum of finished transactions user is involved
• gdtSum: sum of gdt of user in cent with 2 places (Nachkommastellen)
• timeUsed: time used for getting data from db in seconds, only for analyse backend performance

Transaction:

• name: name of other involved party or empty if unknown (if other party don't belong to group)
  • if type is send, name is name of receiver
  • if type is receive, name is name of sender
  • if type is creation currently I use a static string ("Gradido Akademie)
• email: optional, only if type is send or receive and other user is known
• pubkey: optional, only if type is send or receive and other user isn't known, hexadecimal representation of 32 Byte public key of user [0-9a-f]
• type: type of transaction
  • creation: user has get gradidos created
  • send: user has send another user gradidos
  • receiver: user has received gradidos from another user
• transaction_id: id of transaction in db, in stage2 also the hedera sequence number of transaction
• date: date of ordering transaction (booking date)
• balance: Gradido Cent, 4 Nachkommastellen (2 Reserve), 1920000 = 192,00 GDD
• memo: Details about transaction

Creation transaction

Makes a creation transaction to create new Gradido

This assumes you have set

unsecure.allow_auto_sign_transactions = 1

in the Login-Server, so transactions can be auto-signed directly with handing in the transaction. Normally a forwarding to login-server check transactions side is necessary to minimize security risks. // TODO this is not documented

Request

POST http://localhost/api/createCoins

with

{
	"session_id" : -127182,
	"email": "max.musterman@gmail.de",
	"amount": 10000000,
	"target_date":"2021-02-19T13:25:36+00:00", 
	"memo":"AGE",
	"auto_sign": true
}

OR

{
	"session_id" : -127182,
	"username": "Maxi_786",
	"amount": 10000000,
	"target_date":"2021-02-19T13:25:36+00:00", 
	"memo":"AGE",
	"auto_sign": true
}

OR

{
	"session_id" : -127182,
	"pubkey": "038a6f93270dc57b91d76bf110ad3863fcb7d1b08e7692e793fcdb4467e5b6a7",
	"amount": 10000000,
	"target_date":"2021-02-19T13:25:36+00:00", 
	"memo":"AGE",
	"auto_sign": true
}

• session_id: optional, only used if cookie GRADIDO_LOGIN not exist and no sesion_id in php session
• email or username or pubkey: used to identify how gets the gradidos (email and username are only aliases for pubkey)
• amount: gdd amount to transfer in gradido cent (10000000 = 1000,00 GDD)
• memo: text for receiver, currently saved as clear text in blockchain
• auto_sign: if set to true, transaction will be directly signed on login-server and proceed if needed signs are there if set to false, transaction must be signed after on http://localhost/account/checkTransactions

Response

In case of success returns:

{
	"state":"success",
	"timeUsed": 0.0122
}

• timeUsed: time used for getting data from db in seconds, only for analyse backend performance

Send transaction

Make a simple GDD Transaction, send Coins from logged in user to another.

This assumes you have set

unsecure.allow_auto_sign_transactions = 1

in the Login-Server, so transactions can be auto-signed directly with handing in the transaction. Normally a forwarding to login-server check transactions side is necessary to minimize security risks. // TODO this is not documented

Request

POST http://localhost/api/sendCoins

with

{
	"session_id" : -127182,
	"email": "max.musterman@gmail.de",
	"amount": 1000000,
	"memo":"a gift",
	"auto_sign": true
}

OR

{
	"session_id" : -127182,
	"username": "Maxi_786",
	"amount": 1000000,
	"memo":"a gift",
	"auto_sign": true
}

OR

{
	"session_id" : -127182,
	"pubkey": "038a6f93270dc57b91d76bf110ad3863fcb7d1b08e7692e793fcdb4467e5b6a7",
	"amount": 1000000,
	"memo":"a gift",
	"auto_sign": true
}

• session_id: optional, only used if cookie GRADIDO_LOGIN not exist and no sesion_id in php session
• amount: amount to transfer, 2000000 = 200,00 GDD
• email or username or pubkey: used to identify how gets the gradidos (email and username are only aliases for pubkey)
• memo: text for receiver, currently saved as clear text in blockchain
• auto_sign: if set to true, transaction will be directly signed on login-server and proceed if needed signs are there if set to false, transaction must be signed after on http://localhost/account/checkTransactions

Response

In case of success returns:

{
	"state":"success",
	"timeUsed": 0.0122
}

• timeUsed: time used for getting data from db in seconds, only for analyse backend performance

Process

Once the transaction was created on community server, send to login-server, signed (if unsecure.allow_auto_sign_transactions = 1 and auto_sign = true) and then send back to community server to be finally put into the database.

After you get this answer you see the new transaction if you request the transaction list or call for the balance.

// TODO balance and at least last transaction must be returned with the call itself

Without auto-sign the transaction is pending on the login-server and waits for the user to review it at http://localhost/account/checkTransactions

// TODO how is this more secure? // TODO Is this in line with our usability goals? // TODO Should this not be handled client side?