A web search API lets a user submit criteria and receive matching records. In a transaction workflow, it supports finding ACH transactions by an individual name or an amount, making large datasets easier to investigate and helping teams respond to customer complaints. section 9.2.2 section 9.6
A simple design accepts one GET query parameter named criteria at /transactions/search. The server decides whether that value represents a name, one amount, or an amount range. Separate fields would simplify server-side handling, while keyword expressions would require more parsing; a single criterion can be less cumbersome for users. section 9.2.2
Listing 9.5 Initial endpoint definition for searches
@router.get( #1
path="/transactions/search", #1
response_model=list[str], #1
summary="Retrieve ACH Transactions", #1
description= #1
"Retrieve the transactions matching #1
➥ the specified criteria.", #1
response_description="ACH Transactions.", #1
response_model_exclude_none=True, #1
tags=["ACH Files"], #1
) #1
async def get_ach_transactions(criteria: str = Query(..., #2
description="Search criteria for transactions")) #2
➥ -> list[str]: #2
return [f"ACH Transactions for {criteria}"] #3
The initial route establishes the endpoint contract: a required criteria query parameter, a transaction-oriented description, and a list response. It clears the initial 404, but needs query and response work before it becomes useful. section 9.2.2
Build the search behavior in small, testable pieces:
- Define a response model for the identifiers and transaction fields that callers need, such as file ID, batch header ID, entry ID, filename, individual name, and amount. section 9.2.2
- Classify criteria with patterns: an amount such as 1.00 uses exact amount lookup; two amounts separated by whitespace form a range; other input is treated as an individual name. section 9.2.2
- Start each lookup from a shared SELECT that joins the ACH file, record, and entry-detail tables, then append the relevant WHERE condition. section 9.2.2
- Use parameter values when executing amount queries, return fetched rows, and map rows into the response model. section 9.2.2
Choosing a transaction query
For criteria matching a decimal amount, search for an exact amount. For two decimal amounts, use SQL BETWEEN to retrieve the range. Otherwise, search individual_name with ILIKE, which makes the name match case-insensitive. These branches let one user-facing field drive distinct database queries. section 9.2.2 section 9.2.2
Search design is also a security and product decision. GET query parameters can appear in web-server, firewall, application, and third-party logs. If searches may include account or tax identification numbers, reconsider the transport and criteria design so sensitive values are not exposed in logs. Audit logging can complement search by recording request details, user interactions, and dashboard activity for accountability and future improvements. section 9.2.2 section 9.6
A useful search API is more than a route that returns data. It needs flexible criteria handling, a response shape that supports the interface, efficient querying for large datasets, and tests that validate required search scenarios. Clear user stories and acceptance criteria help align those choices with stakeholder needs. section 9.6 section 9.2.2
