I find it helpful to have examples on hand when discussing design decisions with my junior dev (or anyone else). Often I’ll get questions about why we can’t just do X, or why we can’t use Laravel’s built-in Y. The answer usually comes down to one of two things: a) I made a design decision because we have timelines, or b) the spec dictates that we behave a certain way in that scenario.
The spec has done an excellent job in avoiding extraneous design decisions, and simply laying out the organizational structure and behavior of an API. This also means… not many examples, and the examples are usually just one way to tackle the problem. You have free reign within the spec to do a lot of things, but as I’m discovering, the obvious solutions often have pitfalls.
Have we considered making an official-unofficial “library” of request cycles? My idea is to define a schema with examples of many database design patterns (one to many, many to many, many to many with pivot data, polymorphic relations, polymorphic w/ pivot data). Once we have this toy schema, we write up example request cycles showing what kinds of requests to make and what the hypothetical response could be. This way we have examples of common design problems and suggestions about how to implement them within spec.
And just to be clear there will be no code, and no sample implementation. This is simply example HTTP requests and suggested HTTP responses. They should be annotated so people know what the request is trying to accomplish.