Skip to content

Commit a757675

Browse files
rbessinrbessin
committed
added postman api testing documentation
1 parent 680bca1 commit a757675

1 file changed

Lines changed: 323 additions & 0 deletions

File tree

  • .claude/skills/general-practices/postman-api-testing

‎.claude/skills/general-practices/postman-api-testing/SKILL.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
name: postman-api-testing
3+
description: >-
4+
Guide for using Postman to test and interact with the FinishLine API during development.
5+
Use when testing API endpoints, debugging backend issues, verifying request/response
6+
formats, or when asked how to use Postman with the local development environment.
7+
---
8+
9+
# Postman API Testing
10+
11+
> **Summary:** Postman enables developers to test API endpoints locally during development. This guide covers setup, authentication, common workflows, and troubleshooting for the FinishLine API running on localhost:3001.
12+
13+
## Overview
14+
15+
Postman is an API development tool that allows you to make HTTP requests to the FinishLine backend without needing the frontend interface. This is particularly useful for:
16+
17+
- Testing new endpoints during development
18+
- Debugging backend issues in isolation
19+
- Verifying request and response formats
20+
- Exploring available API data without UI constraints
21+
22+
All API requests in local development target `http://localhost:3001`, which is the Express server running on your machine. Many endpoints require authentication using a user ID obtained from the `/users` endpoint.
23+
24+
## Prerequisites
25+
26+
Before you begin, ensure you have:
27+
28+
- [Postman](https://www.postman.com/downloads/) installed
29+
- The FinishLine backend running locally
30+
- The PostgreSQL database running in Docker with seeded data
31+
32+
## Verifying the API is Running
33+
34+
Before making requests, confirm the backend is accessible:
35+
36+
1. Start the backend server if not already running:
37+
38+
```bash
39+
yarn backend:dev
40+
```
41+
42+
2. The console should show the server listening on port 3001
43+
44+
3. Make a test request to the base URL in Postman: `GET http://localhost:3001`
45+
46+
If the API is not configured properly or you hit a non-existent endpoint, you'll receive a "Welcome to NER" message. This indicates the route handler doesn't exist.
47+
48+
## Base URL
49+
50+
All API requests in local development should be made to:
51+
52+
```
53+
http://localhost:3001
54+
```
55+
56+
This is the Express server listening for HTTP requests. The backend handles routing, authentication, and business logic before querying the PostgreSQL database.
57+
58+
## Authentication
59+
60+
Many endpoints in the FinishLine API require authentication to enforce permission checks and organization scoping. Here's how to authenticate your Postman requests:
61+
62+
### Step 1: Get a User ID
63+
64+
First, fetch a user from the `/users` endpoint:
65+
66+
1. Create a new GET request in Postman
67+
2. Enter URL: `http://localhost:3001/users`
68+
3. Click **Send**
69+
4. The response contains an array of users with their `userId` fields
70+
5. Copy a `userId` from any user in the response (typically a string like `"abc-123-def"`)
71+
72+
### Step 2: Add Authorization Header
73+
74+
For endpoints requiring authentication:
75+
76+
1. Navigate to the **Headers** tab in your request
77+
2. Add a new header with:
78+
- **Key:** `authorization`
79+
- **Value:** `<paste-the-user-id-here>`
80+
3. Send your request
81+
82+
Without proper authorization, protected endpoints will return `401 Unauthorized` or `403 Forbidden` responses depending on the permission level required.
83+
84+
## Common Workflows
85+
86+
### Fetching All Users
87+
88+
**Endpoint:** `GET http://localhost:3001/users`
89+
90+
**Purpose:** Retrieve all users in the system. Use this to find user IDs for authentication in other requests.
91+
92+
**Authentication:** Not required
93+
94+
**Steps:**
95+
96+
1. Create a new request in Postman
97+
2. Set method to **GET** using the dropdown menu
98+
3. Enter URL: `http://localhost:3001/users`
99+
4. Click **Send**
100+
101+
**Response:** Array of user objects with `userId`, `firstName`, `lastName`, `email`, and role information.
102+
103+
### Fetching All Projects
104+
105+
**Endpoint:** `GET http://localhost:3001/project`
106+
107+
**Purpose:** Retrieve all projects in the system. Useful for finding existing project data, WBS numbers, or materials associated with projects.
108+
109+
**Authentication:** Check the route definition to confirm if required
110+
111+
**Steps:**
112+
113+
1. Create a new request
114+
2. Set method to **GET**
115+
3. Enter URL: `http://localhost:3001/project`
116+
4. Add authorization header if needed (see Authentication section)
117+
5. Click **Send**
118+
119+
**Response:** Array of project objects with details like `projectId`, `name`, `wbsNum`, `status`, `teams`, and nested data.
120+
121+
### Making Authenticated Requests
122+
123+
For any endpoint that requires authentication:
124+
125+
1. Fetch a user ID from `GET /users` (see above)
126+
2. Add the `authorization` header with the user ID as the value
127+
3. Make your request normally
128+
129+
If you forget authorization on a protected route, the response will include an error message indicating permission denied or unauthorized access.
130+
131+
### Creating or Updating Data (POST Requests)
132+
133+
When testing endpoints that create or modify data:
134+
135+
1. Set request method to **POST**
136+
2. Add authentication header with a valid user ID
137+
3. Navigate to the **Body** tab
138+
4. Select **raw** and **JSON** format from the dropdown
139+
5. Enter the request payload as valid JSON
140+
6. Click **Send**
141+
142+
Example JSON body structure (varies by endpoint):
143+
144+
```json
145+
{
146+
"name": "New Project",
147+
"description": "Project description",
148+
"leadId": "user-id-here"
149+
}
150+
```
151+
152+
Refer to the backend route validation rules in `src/backend/src/routes/` to determine required fields and formats.
153+
154+
## Using Postman Features
155+
156+
### Request Type Selection
157+
158+
The dropdown menu to the left of the URL field allows you to select the HTTP request method. FinishLine follows this convention:
159+
160+
- **GET** — Retrieve data (read operations)
161+
- **POST** — Create new data, update existing data, or delete data
162+
163+
Note: FinishLine does not use `PUT`, `PATCH`, or `DELETE` HTTP methods. All mutations use `POST`.
164+
165+
### Key Tabs in Postman
166+
167+
Postman provides several tabs for configuring requests:
168+
169+
- **Params** — Add query parameters to your URL (e.g., `?limit=10&offset=0`)
170+
- **Authorization** — Alternative way to set auth (use Headers tab for FinishLine)
171+
- **Headers** — Add HTTP headers like `authorization`, `Content-Type`, `organizationId`
172+
- **Body** — Include request payload for POST requests (select raw → JSON format)
173+
174+
## Finding Endpoint URLs
175+
176+
To discover available endpoints and their paths:
177+
178+
1. **Check route files:** Backend routes are defined in `src/backend/src/routes/{feature}.routes.ts`
179+
2. **Combine base paths:** The full URL is `index.ts` base path + route path
180+
- Example: If `index.ts` has `app.use('/calendar', calendarRouter)` and the route defines `POST /shop/create`, the full endpoint is `POST /calendar/shop/create`
181+
3. **Review validation:** Route files show which fields are required and their validation rules using `express-validator`
182+
183+
## Organization Scoping
184+
185+
FinishLine is a multi-tenant application. Most endpoints filter data by `organizationId`. In local development with seed data, the organization ID is typically included automatically via middleware.
186+
187+
If an endpoint requires an explicit `organizationId` header:
188+
189+
1. Go to the **Headers** tab
190+
2. Add key: `organizationId`
191+
3. Set value to a valid organization ID (check your seed data or database)
192+
193+
## Troubleshooting
194+
195+
### "Welcome to NER" Message
196+
197+
**Problem:** You receive a plain text "Welcome to NER" response.
198+
199+
**Cause:** The endpoint URL is incorrect or the route doesn't exist. This is the default response when Express can't find a matching route handler.
200+
201+
**Solution:**
202+
203+
- Double-check the endpoint URL for typos
204+
- Verify the HTTP method matches the route definition (GET vs POST)
205+
- Confirm the route is registered in `src/backend/index.ts`
206+
- Check that the feature router is imported and mounted on the correct base path
207+
208+
### Connection Refused or Network Error
209+
210+
**Problem:** Postman cannot connect to `http://localhost:3001`.
211+
212+
**Cause:** The backend server is not running.
213+
214+
**Solution:**
215+
216+
- Start the backend: `yarn backend:dev` or `yarn start`
217+
- Verify the console shows "Server listening on port 3001"
218+
- Check no other process is using port 3001
219+
- Wait a few seconds for the server to fully start after running the command
220+
221+
### 401 Unauthorized or 403 Forbidden
222+
223+
**Problem:** The endpoint returns a 401 or 403 error.
224+
225+
**Cause:** Missing or invalid authentication, or insufficient permissions.
226+
227+
**Solution:**
228+
229+
- Ensure you've added the `authorization` header with a valid user ID
230+
- Verify the user ID exists in the database (check `/users` response)
231+
- Confirm the user has sufficient permissions for the operation (check the service method's permission check)
232+
- Try using a different user with higher privileges (e.g., an admin user)
233+
234+
### 400 Bad Request
235+
236+
**Problem:** The endpoint returns a 400 error with validation messages.
237+
238+
**Cause:** The request payload doesn't match the validation rules defined in the route.
239+
240+
**Solution:**
241+
242+
- Check the route file (`src/backend/src/routes/`) for validation rules
243+
- Verify all required fields are present in the request body
244+
- Ensure field types match expectations (string, number, date, boolean)
245+
- Check for typos in field names
246+
- Review the error response for specific validation failure details
247+
248+
### Date Format Issues
249+
250+
**Problem:** Date fields are rejected or cause errors.
251+
252+
**Cause:** Invalid date string format.
253+
254+
**Solution:**
255+
256+
- Use ISO 8601 date format: `"2025-02-16T12:00:00.000Z"`
257+
- Or use a simpler format: `"2025-02-16"`
258+
- Avoid relative dates like "yesterday" or "last week"
259+
- The backend controller parses date strings with `new Date()`, so any format recognized by JavaScript's Date constructor works
260+
261+
### Empty or Unexpected Response
262+
263+
**Problem:** The endpoint returns 200 OK but the data is empty or not what you expected.
264+
265+
**Cause:** Data may be filtered by organization scope, soft-deleted, or the query returned no matches.
266+
267+
**Solution:**
268+
269+
- Check the database for relevant data: `yarn prisma:studio`
270+
- Verify `dateDeleted` is `null` on the records you expect to see
271+
- Confirm the records belong to the organization you're querying
272+
- Review the service method's query filters and transformers
273+
274+
## Available Endpoints Reference
275+
276+
This table lists some core endpoints available in the FinishLine API. For a complete list, review the route files in `src/backend/src/routes/`.
277+
278+
| Endpoint | Method | Description | Auth Required |
279+
| ---------- | ------ | ----------------------------------------- | ------------- |
280+
| `/users` | GET | Fetch all users with roles and settings | False |
281+
| `/project` | GET | Fetch all projects with WBS and team data | True |
282+
283+
_Note: This table is incomplete. When discovering new endpoints, add them here with their method, purpose, and authentication requirements._
284+
285+
## Key Rules
286+
287+
- The base URL is always `http://localhost:3001` for local development
288+
- Use **GET** for reads and **POST** for all mutations (create, update, delete)
289+
- Authentication uses the `authorization` header with a user ID value
290+
- Fetch user IDs from the `/users` endpoint before testing protected routes
291+
- Full endpoint URLs combine the base path from `index.ts` and the route path
292+
- Expect "Welcome to NER" for non-existent or incorrectly typed endpoints
293+
- Validate request payloads against the route's `express-validator` rules
294+
- Organization scoping is enforced — data is filtered by `organizationId`
295+
296+
## Common Mistakes
297+
298+
- **Not starting the backend server** before making requests
299+
- **Forgetting the authorization header** on protected endpoints
300+
- **Using incorrect HTTP methods** (e.g., PUT or DELETE instead of POST)
301+
- **Mistyping the endpoint URL** (check the full path: base + route)
302+
- **Not checking route validation rules** before constructing POST request bodies
303+
- **Assuming all endpoints require authentication** — check the route definition
304+
- **Ignoring 400 error details** — the response usually explains what's invalid
305+
306+
## Reference Files
307+
308+
- `src/backend/index.ts` — Route registration and middleware setup
309+
- `src/backend/src/routes/{feature}.routes.ts` — Route definitions with HTTP methods and validation rules
310+
- `src/backend/src/controllers/{feature}.controllers.ts` — Request handling logic
311+
- `src/backend/src/services/{feature}.services.ts` — Business logic and permission checks
312+
313+
## Tips for Efficient Testing
314+
315+
- **Save requests in collections:** Organize related endpoints into Postman collections for easy reuse
316+
- **Use environments:** Create a Postman environment with variables like `baseUrl` and `userId` to avoid repetitive typing
317+
- **Inspect responses:** Check the response status, headers, and body to verify expected behavior
318+
- **Test edge cases:** Try invalid inputs, missing fields, and unauthorized access to verify error handling
319+
- **Review console logs:** The backend terminal shows request logs and error stack traces
320+
321+
## Contributing to This Documentation
322+
323+
If you discover additional endpoints, common workflows, or troubleshooting tips, please update this document following the same structure. Add new endpoints to the reference table, new workflows under Common Workflows, and new issues under Troubleshooting.

0 commit comments

Comments
 (0)