{% extends "base.html" %} {% block title %}API Documentation - Project Ploughshares{% endblock %} {% block content %}

Project Ploughshares API Documentation

Endpoints

1. List All Transactions

GET /api/transactions

Complete Example:
curl -X GET "http://{{ server_name }}/api/transactions"
Response:
[
  {
    "id": 1,
    "transaction_type": "Purchase Order",
    "company_division": "Test Corp",
    "amount": "1000.00",
    "recipient": "Test Recipient",
    "description": "Test transaction",
    "approved": false,
    "created_at": "2025-07-23T22:43:35.520130"
  }
]

2. Get Transaction Details

GET /api/transaction/{id}

Complete Example:
curl -X GET "http://{{ server_name }}/api/transaction/1"
Response:
{
  "navigation": {
    "next_id": null,
    "prev_id": null
  },
  "transaction": {
    "id": 1,
    "transaction_type": "Purchase Order",
    "company_division": "Test Corp",
    "address_1": "",
    "address_2": "",
    "city": "",
    "province": "",
    "region": "",
    "postal_code": "",
    "is_primary": false,
    "source_date": null,
    "source_description": "",
    "grant_type": "",
    "description": "Test transaction",
    "amount": "1000.00",
    "recipient": "Test Recipient",
    "commodity_class": "",
    "contract_number": "",
    "comments": "",
    "approved": false,
    "approved_at": null,
    "approved_by": null,
    "created_at": "2025-07-23T22:43:35.520130"
  }
}

3. Create New Transaction

POST /api/transaction

Note: All transactions created via API are set to "pending approval" status by default. They must be explicitly approved using the approval endpoint before being considered valid.

Required Fields:
  • transaction_type - Type of transaction (e.g., "Purchase Order", "Subcontract")
  • company_division - Company or division name
  • recipient - Recipient of the transaction
Optional Fields:
  • amount - Transaction amount (defaults to 0)
  • description - Transaction description
  • address_1, address_2, city, province, region, postal_code - Address fields
  • source_date - Date in YYYY-MM-DD format
  • source_description - Source description
  • grant_type - Type of grant
  • commodity_class - Commodity classification
  • contract_number - Contract number
  • comments - Additional comments
  • is_primary - Boolean flag (defaults to false)
Complete Example:
curl -X POST "http://{{ server_name }}/api/transaction" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_type": "Purchase Order",
    "company_division": "Example Corp",
    "recipient": "Test Recipient",
    "amount": 1000.00,
    "description": "Test transaction"
  }'
Response:
{
  "message": "Transaction created successfully and is pending approval",
  "transaction_id": 2
}

4. Update Transaction

PUT /api/transaction/{id}

Note: This endpoint only updates transaction details. It does not change the approval status of a transaction. To approve a transaction, use the dedicated approval endpoint.

Complete Example:
curl -X PUT "http://{{ server_name }}/api/transaction/2" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_type": "Purchase Order",
    "company_division": "Updated Corp",
    "description": "Updated transaction",
    "amount": 1500.00,
    "recipient": "Updated Recipient"
  }'
Response:
{
  "message": "Transaction updated successfully"
}

5. Delete Transaction

DELETE /api/transaction/{id}

Complete Example:
curl -X DELETE "http://{{ server_name }}/api/transaction/3"
Response:
{
  "message": "Transaction deleted successfully"
}

6. Get Pending Transactions

GET /api/transactions/pending

Complete Example:
curl -X GET "http://{{ server_name }}/api/transactions/pending"
Response:
[
  {
    "id": 1,
    "transaction_type": "Purchase Order",
    "company_division": "Test Corp",
    "amount": "1000.00",
    "recipient": "Test Recipient",
    "description": "Test transaction",
    "approved": false,
    "created_at": "2025-07-23T22:43:35.520130"
  }
]

7. Approve Transaction

POST /api/transaction/{id}/approve

Important: This endpoint provides human-in-the-loop verification. All transactions (especially those created via API) require explicit approval before being considered valid. The system automatically records the approval with a standard identifier.

Complete Example:
curl -X POST "http://{{ server_name }}/api/transaction/2/approve"
Response:
{
  "message": "Transaction approved successfully"
}
{% endblock %} {% block scripts %} {% endblock %}