Module 04: Web, APIs, And Integration

Understand how systems talk to each other through HTTP, APIs, contracts, auth, and error behavior.

An API is a promise between systems.

client sends method + path + headers + body
server validates + acts + returns status + headers + body

If the promise is vague, integration becomes guesswork.

An API is like a restaurant order ticket. If the ticket says “food please”, the kitchen guesses. If it says “one veg thali, no onion, table 7”, the kitchen can act.

Every endpoint needs:

• Method and path.
• Auth requirement.
• Request schema.
• Response schema.
• Error responses.
• Idempotency behavior.
• Rate limits if needed.
• Example request and response.

frontend object
  -> JSON request body
  -> backend validation schema
  -> domain object
  -> database row
  -> response DTO
  -> frontend state

Design ticket APIs:

• POST /tickets
• GET /tickets
• GET /tickets/{id}
• POST /tickets/{id}/comments
• PATCH /tickets/{id}/status
• POST /tickets/{id}/attachments

For each endpoint, write:

• Who can call it.
• What request it accepts.
• What response it returns.
• What errors are expected.

• Missing auth token.
• User tries to access another user’s ticket.
• Request body is invalid JSON.
• Required field is missing.
• Status transition is illegal.
• Upload is too large.
• Client retries a create request.

Ask an agent:

Review this API contract. Find ambiguous fields, missing errors, auth gaps,
idempotency problems, and mismatches between endpoint names and behavior.

• Why is authentication different from authorization?
• Why should the backend validate even if the frontend already validated?
• When should an endpoint be idempotent?
• What error should an unauthorized user receive?
• What should clients do with a 409?
• What makes an API easy for another engineer to use?

1. Create portfolio/04-web-apis-and-integration/api-contract.md.
2. Write six ticket endpoints.
3. Add success and error examples.
4. Call one real API with curl.
5. Build or mock two endpoints.
6. Add validation tests.
7. Record request and response evidence.

• Another learner can build a client using only your contract.
• Expected errors are explicit.
• Auth and authorization rules are visible.
• You have called and inspected real HTTP traffic.