API

The page will explain how the API works and which endpoints exist in Project Next.

Generate an API key at /admin/api-keys. Remember to copy the API key when you generate the key since the key cannot be shown again. When the key is generated, give the key the permission it needs.

Authorization

To Authorize requests add the key to the Authorization header in the request, like this:

Authorization: id=1&key=deve74a7dc1d7479db2ddc42c7df79575b6912cfcc9b4aec8cfaafa7832a8

Here is a full example in python:

import requests

READ_SHOPS_URL = "http://localhost/api/shop/getAll"
API_KEY = "id=1&key=deve74a7dc1d7479db2ddc42c7df79575b6912cfcc9b4aec8cfaafa7832a8"

headers = {
    "Authorization": API_KEY
}

response = requests.get(READ_SHOPS_URL, headers=headers)

if (response.status_code == 200):
    print("Success")
    print(response.json())
else:
    print("Failure")
    print(response.json())

Error handling

At every endpoint, the status code must be checked. If these codes are unfamiliar, read more here. If an error occurs an error status code will be set and errors will most likely be in this form:

{
    errorCode: string,
    errors: {
        message: string
    }[]
}

Sometimes the object can contain other fields with useful information about what is wrong. These cases will most likely only happen during development.

Endpoints

Get all shops

• URL: /api/shop/getAll
• METHOD: GET
• PERMISSION: SHOP_READ
• RETURN: Array of all shops

Get product by barcode

• URL: /api/shop/product/barcode
• METHOD: POST
• PERMISSION: PRODUCT_READ
• RETURN: Product with price

PARAMETES:

{
    shopId: number,
    barcode: string,
}

This method returns a product with price by its barcode

Create purchase

• URL: /api/shop/purchase/createByStudentCard
• METHOD: POST
• PERMISSION: PURCHASE_CREATE_ONBEHALF
• RETURN: Remaining balance with a user object

PARAMETERS:

{
    shopId: number,
    studentCard: string,
    products: {
        id: number,
        quanity: number
    }[]
}

The method will transfer money from the user to the shop account. In the parameter there can be no duplicate entries of a product. If there are duplicated the quantity mush be changed.

Connect StudentCard

• URL: /api/users/connectStudentCard
• METHOD: POST
• PERMISSION: USERS_CONNECT_STUDENT_CARD
• RETURN: User

PARAMETERS:

{
    studentCard: string
}

This method will connect a studentCard to a user that has clicked on a button at the webpage.

Examples

Create a purchase

import requests

PURCHASE_URL = "http://localhost/api/shop/purchase/createByStudentCard"
API_KEY = "id=1&key=deve74a7dc1d7479db2ddc42c7df79575b6912cfcc9b4aec8cfaafa7832a8"

data = {
    "shopId": 1,
    "studentCard": "harambeCard",
    "products": [
        {"id": 1, "quantity": 2},
        {"id": 2, "quantity": 5}
    ]
}

headers = {
    "Authorization": API_KEY
}

response = requests.post(PURCHASE_URL, json=data, headers=headers)

if (response.status_code == 200):
    print(response.json())
else:
    print(response.json())