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.
EDIT:
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.
So, I like the intent of this to provide a concrete set of examples of best practices within the spec, but I’m not sure you’ll get much support for this initiative as designed because it adds a unofficial but highly opinionated context to the discussion of possibilities within the spec.
You also conflate database design patterns with API design, which is a huge part of the problem with CRUD APIs - you need to know too much about its implementation to effectively use it.
REST is not DB over HTTP. A good DB model is almost always an extremely poor resource and message model. The proper way to bring new developers up to speed is to coach them on better resource and interaction design, and reinforce the separation of concerns along with the need for loosely coupled client and server.
I don’t have enough experience with modern PHP and it’s frameworks, but my suggestion would be to focus the conversation on how different designs enhance the desired properties of your API, like abstracting away information like the DB design patterns.
I realize staying un-opinionated is a goal of the project, but most of the questions I’ve read here are asking CRUD questions. I honestly think leading by example is the best approach.
Yes, but that requires the assumption that CRUD is a design model to be pushed. Without putting words in anyone’s mouth, I would venture that the writers of the spec range from pragmatic on the adoption of hypermedia over time to outright evangelists. In either case I would find it unlikely they would be interested in furthering a design paradigm with inherent and well known drawbacks.
If you want a CRUD API with all it’s drawbacks, there are existing tools which are better suited and supported for the style like OAS. JSONAPI is a hypermedia format with CRUD like concessions and conventions to allow for phased adoption and understanding of a hypermedia API.
The very assertion of database design patterns having any bearing on the API design reinforces my point. The solution to help developers grown in understanding JSONAPI and hypermedia is to teach good hAPI design principles. I often link to my hypermedia guidelines as a way to start them on this path of understanding, and I believe this is the right way to get junior developers to begin to understand the principles of better API design.
Don’t confuse what I mean. I’m saying offer an example of how to implement this in a hypermedia fashion, so that when people come asking how to CRUD, you can simply point them to a better example of how to handle it.
Don’t show them how to CRUD in JSONAPI. Show them how a complex system can completely avoid this design pattern and still offer the kind of functionality they are after. My questions, and the questions I’ve seen around tend to center around wanting to fall back into this mindset. What I’d like to write is a complex sample database, with many common logical pitfalls, along with a non-CRUD example of request cycles.
Like I said, I like the intent to educate and push towards the right design for solutions. It is an interesting proposition in this light, namely because it tackles education from where developers are likely to encounter the material searching for a specific solution to their current pain.
This feels like a subset of a larger action of translating X to JSONAPI with hypermedia, which would be a huge bite as everyone would want to have everything detailed and every major option translated. But in this case I wouldn’t want it to be specifically about JSONAPI either, I think there are pros and cons to multiple hypermedia formats and I wouldn’t want to strictly focus on one at the exclusion of all others.