typespec1-12  Exercise 3: A Design Brief of Your Own
=========================================================

This exercise is writing, so there is no tool output. Below is a model answer for a different small API, in the shape of the chapter's section 1, followed by the three rules a contract cannot enforce.

  Design brief: Plant Swap Service (a model answer for the exercise)

  Who uses it: a community website and a mobile app where neighbours list spare plants and arrange swaps.
  Resources: listings (create, read, change, withdraw), swap requests (create, accept, decline) and members (read only).
  Rules: a listing belongs to one member; a member cannot request a swap on their own listing; a listing with an accepted request cannot be withdrawn; a withdrawn listing stays on record with the status withdrawn.
  Paged: listings (newest first) and a member's requests.
  Authentication: a bearer token on everything except reading listings.
  Versions: version 1 is listings and requests; version 2 adds photos (an optional list of URLs on a listing) and a search call. Neither changes version 1 for existing clients.
  Out of scope: payment, messaging, moderation, notifications.

  Three rules a TypeSpec contract cannot enforce:
    1. A member cannot request a swap on their own listing (it relates two fields: the requester and the listing's owner).
    2. A listing with an accepted request cannot be withdrawn (it depends on the state of another resource).
    3. 'Newest first' ordering of the listing page (the contract can only describe it in text; whether the server follows it is behaviour).

HOW TO CHECK YOUR OWN
  Every resource should have a verb list. Every rule should be either something a decorator can state (a range, a pattern, required, a status code) or something the brief marks as the server's job. If you cannot tell which, write it in the second group: the cross-field and cross-resource rules almost always belong there.
  The 'out of scope' line is part of the design: it records what you decided not to do, so nobody mistakes the contract for a promise about it.
  The three rules above were chosen to show the three usual kinds: two fields in one object, the state of another resource, and behaviour (ordering) that a contract can only describe.

WHY THIS WORKS AS AN ANSWER
---------------------------
The skill the capstone is practising is deciding what belongs in the contract before writing it. A brief that sorts its rules this way tells you what tests the server will need.