Skip to content

API documentation

Jakub Šindelář edited this page Mar 27, 2024 · 11 revisions

API

This project also integrates with embedded keypad and mobile scanner app, which are part of the store and allows customers to order a product directly at store as they are taking their chosen product. The keypad is simple Arduino-like device, which communicates with our website via this API. Mobile scanner is Quasar Capacitor app for Android and iOS with either physical scanner or just camera.

API Protection

Due to the fact, that APIs are used by simple embedded device, which runs compiled static code, we don't use OAuth or other token based access system. It is simply HTTPS and pre-shared API secret key, which is sent in header with each request. All APIs in small-business-fridge are currently protected in this manner as there are no public functions.

HTTP header

By default, each request has to contain header called 'sbf-API-secret' and value of the secret key, which is supplied in config.js file.
If the secret key is wrong or not sent at all, API returns Status code: 400 Bad Request and JSON object with error and link to this documentation.

Custom Header example
sbf-API-secret: vErYs3cR3tK3yPr3fEr4bLyR4nD0mH4sh

API functions

customerName

Find user's display name via keypad Id.

GET /api/customerName

Considerations for user display name search

Very straightforward function. Supply customer's keypadId (Number). If supplied keypadId is found in the database, API returns JSON with string containing customer's display name. If supplied keypadId does not exist in the database, API returns Status code: 404 Not Found and JSON with string "NOT_FOUND". If supplied keypadId is not a natural number, API returns Status code: 400 Bad Request and JSON object with error and link to this documentation.

Parameters

Name Type Description
customer number Required. The query contains number which represents customer's keypadId.

Example

Suppose you want to find display name for customer with keypadId 3.

Request

curl -H "sbf-API-secret: secret_key" https://example.com/api/customerName?customer=3

Results

Status: 200 OK
"John Smith"

keypadOrder

Order a specified product with specified customer via keypad Id.

POST /api/keypadOrder

Considerations for ordering product

Supply customer's keypadId (Number) and product's keypadId (Number). If customer is found, then function continues to search for product. If product is found, function continues to search for product's delivery, which has amount_left greater than zero. If all those prerequisites are met, then order is made just like when user orders via website. Additionally the parameter keypadOrder is set to true in the order document to distinguish orders made via website and via API. API returns Status code: 200 OK and object containing user object, product name and price.
If user is not found, API returns Status code: 404 Not Found and JSON with string "USER_NOT_FOUND".
If product is not found, API returns Status code: 404 Not Found and JSON with string "PRODUCT_NOT_FOUND".
If there are no deliveries with amount_left greater than zero, API returns Status code: 404 Not Found and JSON with string "STOCK_NOT_FOUND".

Parameters

Name Type Description
customer number Required. The query contains number which represents customer's keypadId.
product number Required. The query contains number which represents product's keypadId.

Example

Suppose you are customer with keypadId 2 and want to order product with keyPadId 4.

Request

curl -H "sbf-API-secret: secret_key" -H "Content-Type: application/json" -X POST -d '{"customer":1,"product":3}' https://example.com/api/keypadOrder

Results

Status: 200 OK
{
'user': {
  'admin': false,
  'supplier': false,
  'showAllProducts': false,
  'sendMailOnEshopPurchase': true,
  '_id': '0274653d64113221e1456438',
  'oid': '12cf4401-c897-4165-8259-dc345112db5a',
  'displayName': 'Smith John',
  'email': '[email protected]',
  'keypadId': 1,
  '__v':0,
  'IBAN': 'CZ1234567890123456789012345'
  },
'product': {
  'name': 'Monster Rossi',
  'price': 3
  }
}