API docs by Redocly

Space-Market (4.0.0)

Download OpenAPI specification:

License: MIT

An API ment for communication in a simple market system.

A API inspired by the Space-Market API. Its ment for communication of a simple market system.

auth

These endpoints define how clients can authenticate to the server to create and change protected items.

Authentication Information

This returns information how the API can be used to authenticate for additional permissions.

Responses

Response samples

Content type
application/json
{
  • "method": "NONE"
}

Create authentication token

This creates a authentication token, that can be used to modify specific data.

Request Body schema: application/json
One of
passphrase
string

Responses

Request samples

Content type
application/json
{
  • "passphrase": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "token_valid_until": "string",
  • "refresh_token": "string",
  • "refresh_token_valid_until": "string"
}

Delete authentication token

This invalidates the token, which is used as Bearer for the API. This should also invalidate the refresh token.

Authorizations:
RootAccess

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Refresh token

This creates a new token, with a refresh token as authentication. The refresh token should be used as Bearer.

Authorizations:
UpdateAccess

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "token_valid_until": "string",
  • "refresh_token": "string",
  • "refresh_token_valid_until": "string"
}

info

These show informations about the server

Server Information

This returns preferences and additional information for the frontend.

Responses

Response samples

Content type
application/json
{
  • "version": "Matender v0.0.1-beta",
  • "credit_limit": 2000,
  • "currency": {
    },
  • "energy_unit": "kcal",
  • "mass_unit": "g"
}

products

These define how the products can be used

Returns all products

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a product

Authorizations:
RootAccess
Request Body schema: application/json
name
required
string
price
required
number <int32>

Price in the smallest format of the currency (f.E. cents)

active
required
boolean

If active is false, its considered to be not avaliable. This should not prevent people to buy it, however. Frontend may use this value to add a dialog to notify users of the fact, its not avaliable.

image_id
string <uuid>
required
object or object or object (ProductLabel)

Responses

Request samples

Content type
application/json
{
  • "name": "Mio Mio Cola",
  • "price": 0,
  • "active": true,
  • "image_id": "84c230fd-5520-4984-8119-37365b66fd80",
  • "label": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "Mio Mio Cola",
  • "price": 170,
  • "active": true,
  • "image_id": "b25afde4-07a4-45a3-a99d-bad3a7780cbb",
  • "label": {
    }
}

Returns details about a product

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "Mio Mio Mate",
  • "price": 170,
  • "active": true,
  • "image_id": "b25afde4-07a4-45a3-a99d-bad3a7780cbb",
  • "label": {
    }
}

Updates a product

Authorizations:
RootAccess
path Parameters
id
string <uuid>
Request Body schema: application/json
name
string
price
number <int32>

Price in the smallest format of the currency (f.E. cents)

active
boolean

If active is false, its considered to be not avaliable. This should not prevent people to buy it, however. Frontend may use this value to add a dialog to notify users of the fact, its not avaliable.

image_id
string <uuid>
object or object or object (ProductLabel)

Responses

Request samples

Content type
application/json
{
  • "name": "Mio Mio Mate with pep",
  • "price": 0,
  • "active": true,
  • "image_id": "84c230fd-5520-4984-8119-37365b66fd80",
  • "label": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "Mio Mio Mate with pep",
  • "price": 170,
  • "active": true,
  • "image_id": "b25afde4-07a4-45a3-a99d-bad3a7780cbb",
  • "label": {
    }
}

Deletes a product by ID

Authorizations:
RootAccess
path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

users

Defines how the user is defined and can be used

Get all users

This endpoint returns all users

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create user

This endpoint creates a new user

Request Body schema: application/json
username
required
string
balance
required
number <int32>

The balance of the user in cents

active
required
boolean
track_transactions
boolean

If set to true, transactions should contain the users id as related user id. Setting it to false, the server should remove the user id from related transactions.

avatar_id
string <uuid>

The avatar image for the user.

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "balance": 0,
  • "active": true,
  • "track_transactions": true,
  • "avatar_id": "ceaabbd8-6fdf-460c-878c-7d0ae67338c0"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "balance": 0,
  • "active": true,
  • "track_transactions": true,
  • "avatar_id": "ceaabbd8-6fdf-460c-878c-7d0ae67338c0",
  • "name": "Mio Mio Cola"
}

Returns details about the user

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "balance": 0,
  • "active": true,
  • "track_transactions": true,
  • "avatar_id": "ceaabbd8-6fdf-460c-878c-7d0ae67338c0"
}

Updates a user

path Parameters
id
string <uuid>
Request Body schema: application/json
username
string
balance
number <int32>

The balance of the user in cents

active
boolean
track_transactions
boolean

If set to true, transactions should contain the users id as related user id. Setting it to false, the server should remove the user id from related transactions.

avatar_id
string <uuid>

The avatar image for the user.

Responses

Request samples

Content type
application/json
{
  • "username": "you",
  • "balance": 0,
  • "active": true,
  • "track_transactions": true,
  • "avatar_id": "ceaabbd8-6fdf-460c-878c-7d0ae67338c0"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "username": "you",
  • "balance": 0,
  • "active": true,
  • "track_transactions": true,
  • "avatar_id": "ceaabbd8-6fdf-460c-878c-7d0ae67338c0"
}

Deletes a user by ID

Authorizations:
RootAccess
path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Deposits funds to a user

path Parameters
id
string <uuid>
Request Body schema: application/json
amount
number <int32>

Responses

Request samples

Content type
application/json
{
  • "amount": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "PURCHASE",
  • "amount": 0,
  • "related_user_id": "6038a5c3-28e1-43f7-8a72-a713a7005b26",
  • "related_product_id": "e0da22be-5437-465a-bea9-b80a9c82af7b"
}

Purchase a product (or use up balance) for user

path Parameters
id
string <uuid>
Request Body schema: application/json
product_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "PURCHASE",
  • "amount": 0,
  • "related_user_id": "6038a5c3-28e1-43f7-8a72-a713a7005b26",
  • "related_product_id": "e0da22be-5437-465a-bea9-b80a9c82af7b"
}

images

Define how a image is created and can be obtained.

Due to human error, the server should not expect the client to delete the image, when it is not used anymore. The server should implerment a garbage collection system for that.

Returns the capabilities and guidelines for images

This endpoint informs the UI, what kind of images are allowed by the server.

Responses

Response samples

Content type
application/json
{
  • "accepted_mime_types": [
    ],
  • "maximum_size": 5242880
}

Create a new image

Creates a new image with the provided information.

Request Body schema: multipart/form-data
file
Array of any

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "filename": "44d3e5d4-60a9-4a16-a20b-1b68c2662e1a.png",
  • "hash": "dd593e6cbf80204e5a68bc64c50a4156a3da7569650f61d7cfe6437428a805d4",
  • "filesize": 1048576,
  • "mime_type": "image/png"
}

Returns image metadata

This endpoint offers metadata about the specified image

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "filename": "44d3e5d4-60a9-4a16-a20b-1b68c2662e1a.png",
  • "hash": "dd593e6cbf80204e5a68bc64c50a4156a3da7569650f61d7cfe6437428a805d4",
  • "filesize": 1048576,
  • "mime_type": "image/png"
}

Deletes the image

This will delete the image from the server, removing both the database entry and the file from the server.

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Image as a raw data stream

This endpoint sends the image as a raw image stream.

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "reason": "INVALID_ID"
}

barcodes

Defines how a barcode is crreated and can be used to find different objects.

Find barcode by type and barcode or id

Returns details for the barcode requested.

Request Body schema: application/json
One of
barcode
required
string
type
required
string
Enum: "PRODUCT" "USER"

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "PRODUCT"
}

Response samples

Content type
application/json
[
  • {
    }
]

Creates a barcode for an object

This endpoint allows to create a barcode, which points to a object

Request Body schema: application/json
barcode
required
string
type
required
string
Enum: "PRODUCT" "USER"
linked_object
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "barcode": "string",
  • "type": "PRODUCT",
  • "linked_object": "9d4556b9-8a59-469d-a7ea-6f0f9d203a9a"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "barcode": "string",
  • "type": "PRODUCT",
  • "linked_object": "9d4556b9-8a59-469d-a7ea-6f0f9d203a9a"
}

Get Barcode Details

This endpoint returns the stored data for this barcode

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "barcode": "string",
  • "type": "PRODUCT",
  • "linked_object": "9d4556b9-8a59-469d-a7ea-6f0f9d203a9a"
}

Updates a barcode

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "barcode": "string",
  • "type": "PRODUCT",
  • "linked_object": "9d4556b9-8a59-469d-a7ea-6f0f9d203a9a"
}

Deletes a barcode by ID

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

denominations

Defines what amounts users can depoist.

Get all denominations

This endpoint returns all denominations. The denominations are expected to be defined by the server.

Responses

Response samples

Content type
application/json
[]

transactions

Defines how transactions are stored.

List all transactions

This endpoint returns all transactions, with optional filtering

Request Body schema: application/json
user_id
string <uuid>

The user id to filter for.

Responses

Request samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Response samples

Content type
application/json
[
  • {
    }
]

Create a new transactions

Creates a new transaction with the provided information. This is primarily used for migration.

Request Body schema: application/json
timestamp
required
string <date-time>

The timestamp when the transaction happend

type
required
string
Enum: "PURCHASE" "DEPOSIT"
amount
required
number <int32>
related_user_id
string <uuid>
related_product_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "PURCHASE",
  • "amount": 0,
  • "related_user_id": "6038a5c3-28e1-43f7-8a72-a713a7005b26",
  • "related_product_id": "e0da22be-5437-465a-bea9-b80a9c82af7b"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "PURCHASE",
  • "amount": 0,
  • "related_user_id": "6038a5c3-28e1-43f7-8a72-a713a7005b26",
  • "related_product_id": "e0da22be-5437-465a-bea9-b80a9c82af7b"
}

Get transaction details from id

Get transaction details from the provided id

path Parameters
id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "PURCHASE",
  • "amount": 0,
  • "related_user_id": "6038a5c3-28e1-43f7-8a72-a713a7005b26",
  • "related_product_id": "e0da22be-5437-465a-bea9-b80a9c82af7b"
}

Remove transaction details from id

Remove the transaction details from the id

path Parameters
id
string <uuid>

Responses