Skip to content

Latest commit

 

History

History
133 lines (103 loc) · 4.1 KB

api.md

File metadata and controls

133 lines (103 loc) · 4.1 KB

API

This describes the current (or planned) state of the REST API.

Account

Accounts hold user information required for invoice generation.

A pin is added by the user for additional factor to media presenation.

Verb Resource Description
GET /accounts Get all
GET /accounts/<id> Get by ID
PUT /accounts Create (Probably will be automated action through registration)
POST /accounts/<id> Update any values
PATCH /accounts/<id> Update any values with JSONP
DELETE /accounts/<id> Deletion of own account (this should cleanup more than just within the accounts table) 
{
  "id": "ACCOUNT_UUID",
  "fullname": "Max Mustermann",
  "street": "Musterstraße 12",
  "plz": "78048",
  "city": "Villingen-Schwenningen",
  "pin": "????"
}

Media Mappings

This maps ownership of different authentication media.

Without a separate table there would be no way to enable highly performant (index-based) selection of a user account through through multiple different media ids.

Verb Resource Description
GET /media Get all
GET /media/<id> Get by ID
GET /media?media_identification=<mid>&media_type=<mtype> Get by media specific id and type
PUT /media Create mapping
DELETE /media/<id> Delete mapping 
{
  "id": "MEDIA_UUID",
  "media_identification": "11234asdf34fqv",
  "account": "ACCOUNT_UUID",
  "media_type": "RFID_???_ID|QR_CODE_EXACT_MATCH|APP_NFC|APP_TOKEN...",
  "creation_timestamp": 012343544356,
  "location": "APP|PoS",
  "device_name": "Android ABC|PoS in the Lab",
  "valid_till_timestamp": 012343544356,
}

Different media type can be implemented but should be specified (for different handling). APP_NFC could be an NFC auth through a phone, APP_TOKEN can be a short-live autogenerated token (to be presented via QR code or number input) in case no media is available.

valid_till_timestamp is an optional attribute for use with short-lived media (tokens) that shall always be checked and reject transaction authorization if in the past. If it not exists then a media can never expire.

Products

Products represent whatever can be acquired through a transaction.

Verb Resource Description
GET /products Get all
GET /products?ean=<ean> Get by EAN
PUT /products Create/Override
DELETE /products?ean=<ean> Delete by EAN

Example base data model:

{
 "ean": "1234567890123",
 "price": 1234,
 "description": "Product description",
 "images": [
  "https://example.org/image.png"
 ],
 "name": "Example product"
}

Transactions

Transactions establish and change account balance.

The transactions table shall be emptied monthly for invoice generation. Data will be archived in S3.

This will improve cost effectiveness, query performance while keeping full transaction history for users.

Additionally, in case we fall short to properly calculate the sum of all transaction amounts correctly during the month (for example because of a very unlikely situation of concurrent transactions for the same account) we wil recalculate the sum for validity. If any differences are spotted, then an INCONSISTENCY_CORRECTION transaction will be created so a correct balance will again be displayed from that point on.

Verb Resource Description
GET /transactions Get all
GET /transactions?account=<ACCOUNT_ID> Get by Username
PUT /transactions Create (Override prohibited)
DELETE /transactions/<id> Deletion prohibited, this might just create a canellation transaction 
{
  "id": "TRANSACTION_UUID",
  "timestamp": 012343544356,
  "account_id": "ACCOUNT_UUID",
  "transaction_amount": -5,
  "transaction_result": 10,
  "action": "BUY_PRODUCT|WITHDRAW|DEPOSIT|CANCEL|INCONSISTENCY_CORRECTION",
  "authentication": "USERNAME_PASSWORD|MEDIA_PIN|MEDIA_ONLY,
  "location": "APP|PoS",
  "device_name": "Android ABC|PoS in the Lab"
  "product":{
    // 1:1 Product Object
  }
}