typespec1-6  Exercise 3: A Read-and-Delete Resource
=========================================================

members.tsp (needs @typespec/rest installed; 0.87.0 here):

  import "@typespec/http";
  import "@typespec/rest";

  using Http;
  using Rest;
  using Rest.Resource;

  @service(#{ title: "Members" })
  namespace Members;

  @error
  model ApiError { code: string; message: string; }

  @resource("members")
  model Member {
    @key @visibility(Lifecycle.Read) id: string;
    name: string;
  }

  interface MemberOps extends ResourceRead<Member, ApiError>, ResourceDelete<Member, ApiError> {}

PREDICTION (from reading resource.tsp)
  ResourceRead   : GET /members/{id}    -> 200 with a Member, or the error
  ResourceDelete : DELETE /members/{id} -> a 200 'ResourceDeletedResponse' with no body (the declaration says @statusCode _: 200), or the error
  No 404, no 204, no list and no create.
  I used my own @error model for the error because chapter 6 showed that the library's ResourceError does not compile as one.

Compiled:

  operation                 inputs                                              responses
  GET /members/{id}         path:id                                             200, default
  DELETE /members/{id}      path:id                                             200, default

WHAT HAPPENED
  Prediction confirmed. Two operations, both on /members/{id}; the id is a shared 'MemberKey' parameter; both declare 200 and the generic default.

WHAT A CLIENT COULD AND COULD NOT KNOW
  Could: the paths, the verbs, that the id is a string, the shape of a Member, the shape of the error.
  Could not: that a missing member gives 404 (it may give 200 with an error, or a 500, and only 'default' covers it); that a delete is idempotent; that deleting returns no body in practice (the contract says 200 with a description and no content; a client library may or may not tolerate a body); how to find a member without already having its id (there is no list).
  The status codes cannot be changed from the interface that extends the library's. To state a 404 and a 204 you write your own operation templates, as in the house-style section.

WHY THIS WORKS AS AN ANSWER
---------------------------
Predicting from the library's source first, then checking against the table, shows what the library decides for you. The second half, what the client can't know, is the argument for the chapter's recommendation: use the library when its decisions are your decisions.