263 lines
3.9 KiB
Markdown
263 lines
3.9 KiB
Markdown
# Patriot API
|
|
|
|
The **Patriot API** is a multi-tenant REST API used to manage clients, zones, and users and automatically generate XML files in the format required by Patriot.
|
|
|
|
Each API key has **its own fully isolated dataset**.
|
|
|
|
## 🔐 Authentication
|
|
|
|
All requests require:
|
|
|
|
```
|
|
Authorization: Bearer <API_KEY>
|
|
```
|
|
|
|
If the key is missing, invalid, disabled, or expired → **401 Unauthorized**
|
|
|
|
---
|
|
|
|
## 📘 Common Status Codes
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| **200 OK** | Request successful (read or update) |
|
|
| **201 Created** | Resource successfully created |
|
|
| **204 No Content** | Resource deleted |
|
|
| **401 Unauthorized** | Invalid/missing API key |
|
|
| **404 Not Found** | Client, zone, or user not found |
|
|
| **409 Conflict** | Duplicate user number |
|
|
| **422 Unprocessable Entity** | Validation failed |
|
|
|
|
---
|
|
|
|
## 🧩 Required Headers
|
|
|
|
Some GET requests require client/user IDs in headers:
|
|
|
|
| Header | Purpose |
|
|
|--------|---------|
|
|
| **X-Client-Id** | Selects the client |
|
|
| **X-User-No** | Selects a specific user |
|
|
|
|
---
|
|
|
|
# 📂 API Endpoints
|
|
|
|
## =======================
|
|
## 🔹 CLIENTS
|
|
## =======================
|
|
|
|
## **GET /clients**
|
|
Get full client info.
|
|
|
|
Requires header:
|
|
```
|
|
X-Client-Id: <client_id>
|
|
```
|
|
|
|
---
|
|
|
|
## **PUT /clients**
|
|
Create or update a client (UPSERT).
|
|
|
|
Returns:
|
|
- `201 Created` if new
|
|
- `200 OK` if updated
|
|
|
|
Example JSON:
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"info": {
|
|
"Name": "Customer Name",
|
|
"Location": "Address line 1",
|
|
"area_code": "1604",
|
|
"area": "City",
|
|
"AltLookup": true,
|
|
"AltAlarmNo": "SIA1000101",
|
|
"ConvertType": "None",
|
|
"NoSigsMon": "None",
|
|
"SinceDays": 0,
|
|
"SinceHrs": 0,
|
|
"SinceMins": 0,
|
|
"ResetNosigsIgnored": true,
|
|
"ResetNosigsDays": 0,
|
|
"ResetNosigsHrs": 0,
|
|
"ResetNosigsMins": 0,
|
|
"PanelName": "Panel Type",
|
|
"PanelSite": "Panel location"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## **PATCH /clients**
|
|
Partial update of a client.
|
|
|
|
Example updating only the location:
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"info": {
|
|
"Location": "New Street 99"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## **DELETE /clients**
|
|
Delete entire client and its XML file.
|
|
|
|
```
|
|
{
|
|
"client_id": 1234
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# =======================
|
|
# 🔹 ZONES
|
|
# =======================
|
|
|
|
## **GET /clients/zones**
|
|
List all zones for a client.
|
|
|
|
Requires:
|
|
```
|
|
X-Client-Id: <client_id>
|
|
```
|
|
|
|
---
|
|
|
|
## **PUT /clients/zones**
|
|
Create or update a zone.
|
|
|
|
Example:
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"zone_id": 1,
|
|
"Zone_area": "Entrance",
|
|
"ModuleNo": 0
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## **DELETE /clients/zones**
|
|
Delete a zone.
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"zone_id": 1
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# =======================
|
|
# 🔹 USERS
|
|
# =======================
|
|
|
|
## **GET /clients/users**
|
|
List all users for a client.
|
|
|
|
Requires:
|
|
```
|
|
X-Client-Id: <client_id>
|
|
```
|
|
|
|
---
|
|
|
|
## **GET /clients/users/single**
|
|
Get one user.
|
|
|
|
Headers required:
|
|
|
|
```
|
|
X-Client-Id: <client_id>
|
|
X-User-No: <user_no>
|
|
```
|
|
|
|
---
|
|
|
|
## **POST /clients/users**
|
|
Create a new user.
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"user": {
|
|
"User_Name": "User Number 1",
|
|
"MobileNo": "+4712345678",
|
|
"MobileNoOrder": 1,
|
|
"Email": "user@email.com",
|
|
"Type": "U",
|
|
"UserNo": 1,
|
|
"Instructions": "Optional",
|
|
"CallOrder": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## **PUT /clients/users**
|
|
Update a user (full replace).
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"user": {
|
|
"User_Name": "Changed Name",
|
|
"MobileNo": "+4798765432",
|
|
"MobileNoOrder": 1,
|
|
"Email": "new@email.com",
|
|
"Type": "U",
|
|
"UserNo": 1,
|
|
"Instructions": "Updated",
|
|
"CallOrder": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## **DELETE /clients/users**
|
|
Delete a user.
|
|
|
|
```
|
|
{
|
|
"client_id": 1234,
|
|
"user_no": 1
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
# 🚀 Notes
|
|
|
|
### ✔ Every API key has completely isolated data
|
|
Two different keys can both store client `1234`, but they are **stored separately**.
|
|
|
|
### ✔ XML files stored per key
|
|
Example output directory:
|
|
|
|
```
|
|
out/clients/KeyA/1234.xml
|
|
out/clients/KeyB/1234.xml
|
|
```
|
|
|
|
### ✔ Deleting a client only deletes it for that API key
|
|
|
|
---
|
|
|
|
# 📄 End of README
|