An API endpoint is a URL route that exposes one operation, such as uploading a file, listing files, or retrieving a record. HTTP methods distinguish actions: POST /files uploads, while GET /files retrieves a list. Path placeholders such as :fileId and :recordId identify a particular resource returned by earlier queries. section 4.2
Table 4.2 API overview
| HTTP method |
Uniform resource identifier |
Description |
|
|
|
Uploads a file to the system |
|
|
|
Returns a list of uploaded files |
|
|
|
Returns details on a specific file |
|
|
|
Returns records for a specific file |
|
|
|
Returns details for a specific record |
This route map connects HTTP methods and resource paths to the first file-management operations, from upload through record detail. section 4.2
Design endpoints around tasks a user or application needs to complete, then trace the flow needed to obtain identifiers for later requests. Start with the smallest useful set of operations and add query parameters when users need narrower results, such as files from a date or records from one file. section 4.2
A first retrieval endpoint
A FastAPI route such as @router.get("/files") can return a JSON list. Test it with TestClient by requesting /files, asserting a 200 status, and checking the returned JSON. Deliberately changing the URL, method, expected status, or response verifies that the test actually detects mistakes. section 4.3.1
Use a shared prefix to keep related endpoints consistent. A prefix such as /api/v1/files turns a route like /{file_id}/records into /api/v1/files/{file_id}/records. The /api segment centralizes API-related web-server, firewall, and monitoring rules; v1 leaves room to introduce v2 without forcing consumers into breaking changes. Update tests when a prefix changes, or they will request the old URL and receive 404 errors. section 4.9.1
Grow an endpoint from a testable minimal route into a focused data operation:
- Write a test for the intended URL and expected response; a missing route normally returns 404 during development. section 7.4.1
- Define the route with the needed path identifier and return a temporary value to establish a 200 response. section 7.4.1
- Replace the placeholder with a focused database method and a response model that describes the returned fields. section 7.4.1
- Expose sensitive data only through a separate, on-demand endpoint when users do not always need it; this supports authentication checks, auditing, and less unnecessary data transfer. section 8.6.1
Endpoint shape is a design choice. A company’s batches could appear under a nested company path, but a search endpoint can be more flexible when it accepts criteria such as an amount, amount range, company identifier, or company name. Document the route’s response model, summary, description, and tags so its purpose is visible in API documentation. section 10.5.1 section 10.2.3
Returning operational results
An endpoint can begin by returning an empty list so its test reaches 200, then evolve to declare a list response model and call a data-access method. For example, an OFAC route returns scan results after the supporting result type and SQL access are available. section 11.8.2
