mirror of
https://github.com/IT4Change/gradido.git
synced 2025-12-13 07:45:54 +00:00
229 lines
6.9 KiB
Markdown
229 lines
6.9 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```ini
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"session_id" : -127182,
|
|
"username": "Maxi_786",
|
|
"amount": 10000000,
|
|
"target_date":"2021-02-19T13:25:36+00:00",
|
|
"memo":"AGE",
|
|
"auto_sign": true
|
|
}
|
|
```
|
|
#### OR
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```ini
|
|
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
|
|
|
|
```json
|
|
{
|
|
"session_id" : -127182,
|
|
"email": "max.musterman@gmail.de",
|
|
"amount": 1000000,
|
|
"memo":"a gift",
|
|
"auto_sign": true
|
|
}
|
|
```
|
|
#### OR
|
|
```json
|
|
{
|
|
"session_id" : -127182,
|
|
"username": "Maxi_786",
|
|
"amount": 1000000,
|
|
"memo":"a gift",
|
|
"auto_sign": true
|
|
}
|
|
```
|
|
#### OR
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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?
|
|
|
|
|