Skip to main content

API Reference and Postman Validation Guide

Overview​

The Secure Controlled Guns and Ammunition Inventory Management System (SCGAIMS) exposes a RESTful API developed using Django REST Framework (DRF) to support inventory accountability, issuance operations, return processing, audit logging, discrepancy detection, and investigation management.

The API serves as the primary integration layer between the SCGAIMS backend and client applications while ensuring accountability and traceability of controlled firearms and ammunition.

This document serves as both:

  • API Reference Documentation
  • Postman Testing Guide
  • Validation Evidence Framework
  • Demonstration Guide

API Collection Structure

The Postman Collection is organized into the following functional groups:

scgaims_API_Endpoints

└── Inventory API Collection

    ├── Inventory Operations
    │     └── GET /inventory/
    │
    ├── Issue Inventory Item
    │     ├── POST /issue-item/
    │     └── POST /return-item/
    │
    ├── Records & Auditing
    │     ├── GET /issue-records/
    │     ├── GET /audit-logs/
    │     └── POST /resolve-investigation/
    │
    └── Authentication

Development Environment

Base URL​

http://127.0.0.1:8000

Authentication

Current State​

The current implementation supports local API testing and validation through the Django development environment.

Planned Production Authentication​

Future production implementations will integrate:

Auth0
OAuth 2.0
OpenID Connect (OIDC)
JWT Access Tokens
Role-Based Access Control (RBAC)
Multi-Factor Authentication (MFA)

Authentication requests will be processed through Auth0 before access is granted to protected resources.

Inventory Operations

Retrieve Inventory

Endpoint​

GET /inventory/

Description​

Returns all inventory records currently stored within SCGAIMS.

The endpoint provides visibility into available firearms, ammunition quantities, and managed controlled assets.

Purpose​

This endpoint allows users to:

  • View inventory availability
  • Verify inventory quantities
  • Confirm inventory records
  • Support issuance validation processes

Request​

Method​

GET

URL​

http://127.0.0.1:8000/inventory/

Headers​

None Required

Sample Response​

[
    {
        "id": 1,
        "item_name": "9mm Ammunition",
        "quantity": 5000
    },
    {
        "id": 2,
        "item_name": "Glock 17",
        "quantity": 25
    }
]

Expected Result​

Inventory records successfully returned.

Postman Validation Procedure​

Step 1​

Select:

Get /inventory/

Step 2​

Click:

Send

Step 3​

Verify:

HTTP Status 200 OK

Step 4​

Confirm inventory records are returned.

Screenshot​

Insert Postman Validation Screenshot

Inventory Issuance Operations

Issue Inventory Item

Endpoint​

POST /issue-item/

Description​

Issues firearms or ammunition to an officer for operational use.

Inventory levels are automatically adjusted upon successful completion.

Purpose​

This workflow establishes accountability by recording:

  • Issued asset
  • Quantity issued
  • Receiving officer
  • Transaction timestamps

Business Logic​

Upon execution the system performs:

Inventory Validation
        |
        v
Sufficient Quantity?
        |
        +---- No ---- Reject Request
        |
        +---- Yes ---> Create Issue Record
                        |
                        v
                 Update Inventory
                        |
                        v
                  Generate Audit Log

Request​

Method​

POST

URL​

http://127.0.0.1:8000/issue-item/

Request Body​

{
    "inventory_id": 1,
    "quantity": 120,
    "issued_to": "Officer A"
}

Sample Successful Response​

{
    "message": "Inventory issued successfully"
}

Expected Results​

Issue Record Created

Inventory Quantity Reduced

Audit Log Created

Validation Test​

Attempt to issue more inventory than available.

Expected Result​

{
    "error": "Insufficient inventory available"
}

Screenshot​

Insert Postman Validation Screenshot

Inventory Return Operations

Return Inventory Item

Endpoint​

POST /return-item/

Description​

Processes the return of previously issued firearms or ammunition.

The endpoint evaluates returned quantities against quantities originally issued.

Purpose​

This operation supports:

  • Inventory reconciliation
  • Accountability validation
  • Discrepancy detection

Business Logic​

Inventory Returned
        |
        v
Retrieve Issue Record
        |
        v
Compare Quantities
        |
        +---- Match -------> Close Transaction
        |
        +---- Mismatch ---->
                              |
                              v
                  Flag Discrepancy
                              |
                              v
                 Generate Investigation
                              |
                              v
                     Generate Audit Log

Request​

Method​

POST

URL​

http://127.0.0.1:8000/return-item/

Request Body​

{
    "issue_id": 1,
    "quantity_returned": 100
}

Sample Response​

{
    "message": "Inventory returned successfully"
}

Discrepancy Validation

Scenario 1​

No Discrepancy​

Issued:

120 rounds

Returned:

120 rounds

Result:

Transaction Completed Successfully

Scenario 2​

Discrepancy Detected​

Issued:

120 rounds

Returned:

100 rounds

Result:

Discrepancy Flag = True

Investigation Required

Audit Record Created

Expected Outcome​

Returned quantity evaluated

Inventory adjusted

Investigation generated if required

Screenshot​

Insert Postman Validation Screenshot

Records and Auditing

Get Issue Records

Endpoint​

GET /issue-records/

Description​

Retrieves previously recorded inventory issuance transactions.

Purpose​

Supports:

  • Historical reviews
  • Operational accountability
  • Investigation activities
  • Inventory reconciliation

Request​

Method​

GET

URL​

http://127.0.0.1:8000/issue-records/

Sample Response​

[
    {
        "issue_id": 1,
        "item_name": "9mm Ammunition",
        "quantity_issued": 120,
        "quantity_returned": 100,
        "discrepancy_flag": true
    }
]

Expected Result​

Historical issue records successfully retrieved.

Screenshot​

Insert Postman Validation Screenshot

Get Audit Logs

Endpoint​

GET /audit-logs/

Description​

Retrieves system audit logs generated by SCGAIMS.

Audit logs provide evidence of user activity and accountability for inventory operations.

Purpose​

Supports:

  • Accountability
  • Auditing
  • Investigations
  • Compliance reviews
  • Forensic analysis

Logged Activities​

Examples include:

Inventory Issued

Inventory Returned

Investigation Resolved

Inventory Updated

Administrative Actions

Request​

Method​

GET

URL​

http://127.0.0.1:8000/audit-logs/

Sample Response​

[
    {
        "user_identifier": "admin",
        "action": "Inventory Issued",
        "timestamp": "2026-07-01T10:30:00Z"
    }
]

Expected Result​

Audit records successfully returned.

Screenshot​

Insert Postman Validation Screenshot

Investigation Management

Resolve Investigation

Endpoint​

POST /resolve-investigation/

Description​

Allows authorized personnel to review and resolve investigations generated by inventory discrepancies.

Purpose​

Supports:

  • Investigation management
  • Resolution workflow
  • Accountability reporting

Business Logic​

Investigation Open
        |
        v
Resolution Submitted
        |
        v
Status Updated
        |
        v
Investigation Closed
        |
        v
Audit Record Generated

Request​

Method​

POST

URL​

http://127.0.0.1:8000/resolve-investigation/

Request Body​

{
    "investigation_id": 1,
    "resolution_notes": "Authorized operational ammunition expenditure verified."
}

Example Response​

{
    "message": "Investigation resolved successfully"
}

Expected Result​

Investigation status updated

Resolution notes stored

Audit log generated

Screenshot​

Insert Postman Validation Screenshot

API Testing Scenarios

Test Scenario 1 – Inventory Retrieval

Objective​

Verify inventory visibility.

Endpoint​

GET /inventory/

Expected Result​

Inventory records displayed.

Test Scenario 2 – Inventory Issuance

Objective​

Verify issuance workflow.

Endpoint​

POST /issue-item/

Expected Result​

Inventory reduced.

Issue record created.

Audit record generated.

Test Scenario 3 – Inventory Return

Objective​

Verify return processing.

Endpoint​

POST /return-item/

Expected Result​

Inventory quantity updated.

Test Scenario 4 – Discrepancy Detection

Objective​

Validate discrepancy logic.

Endpoint​

POST /return-item/

Expected Result​

Discrepancy flagged.

Investigation generated.

Test Scenario 5 – Investigation Resolution

Objective​

Validate investigation workflow.

Endpoint​

POST /resolve-investigation/

Expected Result​

Investigation status updated.

Test Scenario 6 – Audit Logging

Objective​

Verify accountability records.

Endpoint​

GET /audit-logs/

Expected Result​

Audit records displayed.

Error Responses

HTTP 400​

Bad Request​

{
    "error": "Invalid request"
}

HTTP 401​

Unauthorized​

{
    "error": "Unauthorized"
}

HTTP 403​

Forbidden​

{
    "error": "Forbidden"
}

HTTP 404​

Resource Not Found​

{
    "error": "Resource not found"
}

Security Controls

The API supports several security controls:

  • Inventory validation
  • Discrepancy detection
  • Audit logging
  • Investigation workflows
  • Environment variable secret management
  • Future Auth0 integration
  • Future RBAC enforcement

Sensitive values such as database credentials and Auth0 secrets are stored outside source code using environment variables.

Conclusion

The SCGAIMS API provides secure access to inventory accountability functions including inventory visibility, issuance operations, return processing, discrepancy handling, investigation resolution, and audit log retrieval. Combined with the Postman Collection, these endpoints enable validation of critical operational workflows while supporting the accountability, transparency, and security governance objectives that motivated the development of the platform.