API Practice Pack

1) Register user

Create a user account for authenticated requests.

Method: POST

URL: http://localhost:3000/api/register

Headers: Content-Type: application/json

Sample request body

{
  "name": "Alice QA",
  "email": "alice.qa@example.com",
  "password": "Password123!"
}

Expected response

// 200 OK
{ "ok": true }

// 409 Conflict
{ "error": "Email already exists." }

// 400 Bad Request
{ "error": "Invalid registration data." }

What to verify (QA)

• Status code matches scenario
• No sensitive details in error messages
• Duplicate email returns 409

2) Login (NextAuth Credentials)

This MVP uses NextAuth credentials. You must send a CSRF token. After login, your browser/session cookie is required for authenticated endpoints.

Method: GET

URL: http://localhost:3000/api/auth/csrf

Headers: (none required)

Then: POST login

Method: POST

URL: http://localhost:3000/api/auth/callback/credentials

Headers: Content-Type: application/x-www-form-urlencoded

Sample body (form)

email=alice.qa@example.com
&password=Password123!
&csrfToken=PASTE_CSRF_TOKEN
&callbackUrl=http://localhost:3000/dashboard

Expected response

// 200/302 depending on NextAuth flow
// NextAuth will set session cookies in the response.
// Verify by calling:
GET /api/auth/session

What to verify (QA)

• After login, call `GET /api/auth/session` and verify user id/email
• Wrong password returns error (commonly 401/200 with error depending on flow)
• Check cookies are present in Postman (Cookie header)

3) List documents

Filters: q, type, status. This endpoint returns documents visible to the actor (user or guest).

Method: GET

URL: http://localhost:3000/api/documents?q=&type=ALL&status=ALL

Headers

// Auth via NextAuth cookies (for users) OR guest cookie (for guest)
Cookie: (paste your session cookies here)

Expected response

{
  "documents": [
    {
      "id": "...",
      "title": "...",
      "type": "TEST_CASE_SET",
      "status": "ACTIVE",
      "createdAt": "..."
    }
  ]
}

What to verify (QA)

• Search is case-insensitive
• Type/status filters work
• No documents from other users

4) Generate a document (QA generation)

Creates a new Document and GeneratedItems in PENDING review status.

Method: POST

URL: http://localhost:3000/api/generate

Headers: Content-Type: application/json

Sample request body

{
  "type": "TEST_CASE_SET",
  "title": "Registration Feature Testing",
  "sourceText": "User can register with email/password. Email must be unique...",
  "domainType": "WEB",
  "detailLevel": "DETAILED",
  "payload": {
    "contextNotes": "Optional extra structured context"
  }
}

Expected response

// 200 OK
{ "documentId": "..." }

// 400 Bad Request
{ "error": "Could not generate..." or "Guest mode is locked..." }

What to verify (QA)

• Document created with correct type/title
• Generated items start as PENDING
• Guest lock-in blocks different generator types

5) Export document (accepted items)

Export includes ACCEPTED items by default. Use `includePending=true` only if you explicitly want it.

Method: GET

URL: http://localhost:3000/api/documents/{documentId}/export?format=md

Headers

// Auth via cookies (user/guest ownership rules apply)
Cookie: (paste your session cookies here)

Expected response

// 200 OK
// Content-Disposition: attachment
// Content-Type: text/plain or text/csv
...exported document content...

What to verify (QA)

• Export does not include rejected items
• Export includes accepted items only (default)
• Forbidden/Not found for other users

6) Quality analysis (uses accepted items)

Sends accepted items to AI and saves QualityAnalysis linked to the document. Demo documents are read-only and regeneration is blocked.

Method: POST

URL: http://localhost:3000/api/documents/{documentId}/quality-analysis

Headers: Cookie + Content-Type: application/json (body can be empty)

Sample request body

{}

Expected response

{
  "analysis": {
    "id": "...",
    "overallScore": 0-100,
    "strengths": ["..."],
    "weaknesses": ["..."],
    "suggestions": ["..."],
    "explainability": { "...": "..." }
  }
}

What to verify (QA)

• Requires at least one ACCEPTED item
• Validation errors return 400
• Demo documents return 403

POST /api/register

• Positive: valid data → 200
• Negative: duplicate email → 409
• Validation: missing fields → 400
• Auth/permission: not required → still expect 200/400/409
• Edge: special characters in password/email

POST /api/generate

• Positive: generate TEST_CASE_SET → 200 documentId
• Negative: guest lock-in to different generator → 400
• Validation: invalid URL format/sourceUrl → 400
• Auth/permission: no session vs guest cookie behavior
• Edge: empty payload object, very long sourceText

GET /api/documents

• Positive: filters work → 200 with documents
• Negative: other user’s doc access → not found/forbidden behavior
• Validation: malformed query params
• Auth/permission: cookie missing → guest fallback or empty list
• Edge: q with special characters

GET /api/documents/{documentId}/export

• Positive: accepted-only export → 200
• Negative: includePending=true with no accepted items
• Validation: invalid format parameter
• Auth/permission: forbidden when not owner; demo read-only still exports
• Edge: long document titles / filename encoding

POST /api/documents/{documentId}/quality-analysis

• Positive: at least one ACCEPTED item → 200 analysis
• Negative: no accepted items → 400 “No accepted items found...”
• Validation: missing docId → 404
• Auth/permission: demo returns 403
• Edge: regenerate multiple times