Java · Advanced level

Advanced level · Module 6: Java Capstone Project · Lesson 1 of 5

Requirements and API Design

Turn the clinic's needs into user stories, resources, endpoints and an error format before coding.

In this lesson you will

  • Write user stories and acceptance criteria
  • Design REST resources, endpoints and status codes

Key concepts

user storyacceptance criteriaresource and endpoint designAPI contract

The lesson

User stories describe needs from the user's side: 'As a receptionist, I want to see today's appointments so I can prepare files.' Acceptance criteria make each story testable, for example 'appointments are listed in time order and cancelled ones are excluded'.

Design the API around resources (patients, appointments) and use HTTP methods consistently: GET /appointments?date=2026-05-04, POST /appointments, PATCH /appointments/{id}/cancel. Decide status codes and the error format up front.

Write the contract as a short document with example requests and responses. It becomes the basis for tests and documentation, and lets others review the design before code exists.

Step by step

  1. Write at least eight user stories with acceptance criteria.
  2. List resources and endpoints with methods and status codes.
  3. Write example JSON for each request and response.
  4. Review the contract with the instructor.

Practice activity

Produce the API contract for the clinic service and get it approved at milestone 1.

Expected result: An approved contract where every user story maps to an endpoint and acceptance criteria.

Check your understanding

  1. What makes a user story testable?

    Show answer

    Clear acceptance criteria.

  2. Why write the API contract before coding?

    Show answer

    It lets the design be reviewed and becomes the basis for tests and documentation.

Taught live by an instructor — online or in person. Free course lessons are for self-study and do not lead to a certificate — see registration options.