Skip to content

REST Machine API (Deprecated)

Jump to bottom
Richard Sommers edited this page Aug 29, 2025 · 2 revisions

The intent of the Makerspace application is to restrict access to machinery by requiring users to tap their ID cards on attached card readers that will use the Makerspace application to determine authorization. For this purpose, the application contains a REST API for the card readers to communicate with.

Caution

This page defines the old, REST API for machine communications. The new system uses websockets for bidirectional, low latency communications and is not documented yet (for shame)

Key

Certain REST endpoints involve checking an API Key. The required key is set in the server's environment variables. See Environment Variables > API_KEY. The card readers will store this same key and send it for comparison during certain mutative API calls.

API Endpoints

Welcome

PUT /api/welcome

Users are required to "check-in" to a zone before using any equipment in that zone.

This endpoint:

  • Ensures the provided user exists in the Users table
  • Adds an entry to the RoomSwipes table to confirm check-in.

Request

JSON body:

{
    "Type": "Welcome",
    "Zone": "4,7,8",
    "ID": "an_id",
    "Key": "super_secret"
}

Zone: The room IDs of the zone a user is signing into.

ID: The University ID (or encrypted card tag) of the scanned ID card

Response

  • HTTP 403 on key mismatch
  • HTTP 406 if user is not in system
  • HTTP 202 if user is in system

Authorization

GET /api/auth

Users must complete all trainings listed for an equipment and have a staff0given access check to be able to activate a machine.

This endpoint:

  • Ensures a user exists in the system
  • Ensures an equipment exists in the system
  • Ensures a user has done a welcome check-in to the zone (if needed)
  • Ensures a user has completed all trainings needed for the equipment
  • Ensures a user has an approved access check for the equipment

Request

Header params:

https://app.address/api/auth?id=an_id&needswelcome=1&zone=7,6,5&type=6

id: The University ID (or encrypted card tag) of the scanned ID card

needswelcome: if 1, the check will fail if the user has not checked into a noted zone

zone: the room ids (comma-separated) of the zone the machine belongs to. This will be considered if needswelcome = 1.

type: the equipment ID

Response

  • HTTP 400 if missing parameters
  • HTTP 406 if user or equipment is not in system
  • HTTP 401 if
    • user requires welcome check-in but has not done so
    • user has not completed all trainings associated with equipment
    • user is missing an approved Access Check
  • HTTP 202 if all criteria is met (or user is staff)

and

JSON body:

{
      "Type": "Authorization",
      "Machine": 6,
      "UID": "an_id",
      "Allowed": 1
}

Machine: the equipment ID of the machine

UID: The University ID (or card tag) of the scanned ID card

Allowed: 1 if all criteria met, 0 otherwise

Status

PUT /api/status

Card Reader Devices are capable of reporting their operating status for display on the website.

This endpoint:

  • Updates the status variables for the specified card reader device

Request

JSON body:

{
    "Type": "Status",
    "Machine": "186bx1",
    "MachineType": "6",
    "Zone": "7",
    "Temp": "28.000",
    "State": "Lockout",
    "UID": "N/A",
    "Time": "9",
    "Source": "Startup",
    "Frequency": "30",
    "Key": "super_secret"
}

Machine: the reader name of the machine

MachineType: the equipment ID of the machine

Zone: the room ID(s) (comma-separated) the machine belongs to

State: The activity state of the machine

UID: The University ID (or card tag) of the scanned ID card, or "N/A" if not active

Time: The length of the most recent (or current) session in seconds

Source: The reason for the status update

Frequency: The number of seconds between scheduled status updates

Response

  • HTTP 403 on key mismatch
  • HTTP 400 if card reader is not in system and can not be created
  • HTTP 200 on success

Help

PUT /api/help

Users can press a button on the card reader to request a staff member to their location.

This endpoint:

  • Toggles the help alert for this reader on the Access Devices webpage.

Request

JSON body:

{
    "Type": "Help",
    "Zone": "4,7,8",
    "Machine": "kmxmill",
    "Key": "super_secret"
}

Zone: The room IDs of the machine

Machine: The reader name of the machine

Response

  • HTTP 403 on key mismatch
  • HTTP 400 if reader is not in system
  • HTTP 200 if success

Message

PUT /api/message

This endpoint:

  • Creates an Audit Log with a specified message

Request

Header params:

https://app.address/api/message/machine_id?message=Hello World!

machine_id: the reader name of the machine

message: the message to post

Response

  • HTTP 400 on missing parameter
  • HTTP 200 on success

Check

GET /api/check

This endpoint:

  • Returns 200

Response

  • HTTP 200

State

GET /api/state/machine_id

This endpoint:

  • Returns the last known state of a machine

Request

URL Path:

https://app.address/api/state/machine_id

machine_id: The name of the reader

Response

  • HTTP 400 if user is not in system
  • HTTP 200 on success and JSON body:
{
    "Type": "State",
    "MachineID": "kmxmill"
    "State": "Lockout"
}

MachineID: The reader name of the machine

State: The state of the machine according to the database

Hours

GET /api/hours/zone_id

This endpoint:

  • Returns the admin-defined hours of a noted zone

Request

URL Path:

https://app.address/api/hours/zone_id

zone_id: The ID number of the zone

Response

  • HTTP 200 JSON body:
{
    "text": "Sunday OPEN: 12:00:00\nSunday CLOSE: 17:00:00\nMonday OPEN: 10:00:00 ...",
    "obj": [
        {
            "id": 104,
            "type": "OPEN",
            "dayOfTheWeek": 1,
            "time": "12:00:00",
            "zoneID": 1
        },
        ...
    ]
}

Inventory

GET /api/inv

This endpoint:

  • Returns a list of inventory items based on defined Type.

Request

JSON body:

{
    "Type": "internal",
    "Key": "inv_super_secret"
}

Type: public / internal / staff / all. Any value other than public requires the Key.

Response

  • HTTP 200 JSON body:
{
    "count": 107,
    "type": "all",
    "items": [
        {
            "id": 239,
            "image": null,
            "name": "BigRep Master Spool PLA Black",
            "unit": "spool",
            "pluralUnit": "spools",
            "count": 4,
            "pricePerUnit": 100,
            "threshold": 0,
            "staffOnly": null,
            "storefrontVisible": null,
            "notes": null,
            "tagID1": 5,
            "tagID2": null,
            "tagID3": null
        },
        ...
    ]
}

Inventory Count

GET /api/inv/item_id

This endpoint:

  • Returns the number currently in the inventory for a specified item

Request

URL Path

https://app.address/api/inv/item_id

item_id: the id of the item to fetch

Response

  • HTTP 200 JSON body:
{
    "count": 107
}

Inventory Add

POST /api/inv/add/item_id

This endpoint:

  • Increments the count of a defined item by the number provided and returns the new count.

Request

URL Path

https://app.address/api/inv/add/item_id

item_id: the id of the item to modify

Request

JSON body:

{
    "Key": "super_secret_inv",
    "Inc": 2,
    "UID": "aa11bb22cc33dd"
}

Inc: Number to increment the count by. Can be negative.

UID: Optional. If set, will attribute any actions to the noted user.

Response

  • HTTP 200 JSON body:
{
    "count": 3,
}

Inventory Set

POST /api/inv/set/item_id

This endpoint:

  • Sets the count of a defined item to the number provided and returns the new count.

Request

URL Path

https://app.address/api/inv/set/item_id

item_id: the id of the item to modify

Request

JSON body:

{
    "Key": "super_secret_inv",
    "Count": 2,
    "UID": "aa11bb22cc33dd"
}

Inc: Number to set the count to. Cannot be negative.

UID: Optional. If set, will attribute any actions to the noted user.

Response

  • HTTP 200 JSON body:
{
    "count": 3,
}
Clone this wiki locally