Update history #1590
Update history #1590
Conversation
- Reorder, since the history part doesn't seem super-relevant today
- Update example library (active model serializers is basically dead)
- Update links to https
- Reorder, since the history part doesn't seem super-relevant today - Update example library (active model serializers is basically dead) - Update links to https
There was a problem hiding this comment.
@sandstrom Thanks a lot for starting to improve the history section. I think it needs to be updated in general to cover the current state more closely. In my perspective JSON:API specification is not that much focused on Ember and Rails anymore as it was in the early days. I think this should be reflected in the history section as well.
@dgeb Would be great to hear your opinion on it.
| * A generic media type that can work across a broad set of use cases, | ||
| including the generally used relationship types | ||
| * Similarity to existing server-side framework practices (and human | ||
| readability for debugging) | ||
| * Ease of implementation on the server side | ||
| * Ease of implementation on the client side |
There was a problem hiding this comment.
I'm not sure if I would phrase the goals like this. It also conflicts, which the marketing statements on the homepage, which focus on
- avoid bike-shedding about API design,
- efficient caching, and
- avoid unnecessary network requests.
If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can be your anti-bikeshedding tool.
By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application.
Clients built around JSON:API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.
Personally I would phrase the goals (looking back) as the following:
- Standardize REST API design to
- avoid bike-shedding about API design, which is not specific to the business requirements, and
- enable development of compatible client- and server-side libraries.
- Built on-top of established REST API patterns to enable incremental adoption and a flat learning curve.
- Reduce the risk of write conflicts on REST API design level (e.g.
PATCHfor updating resources and partial updates of to-many relationships using relationship links). - Support advanced use cases like polymorphic relationships.
- Allow clients to fetch all needed data in a single request to avoid unnecessary network requests (under-fetching).
- Allow clients to request a subset of resource fields to avoid sending unnecessary data over the wire (over-fetching).
There was a problem hiding this comment.
Sure, I just copied text around. I didn't write any of that.
What you suggest sounds good! I've enabled maintainers to make copies in this fork, so you can make whatever changes you want.
Co-authored-by: Jeldrik Hanschke <jelhan@users.noreply.github.com>