Add an introduction to the concepts API Platform is using - Githubissues

api-platform / docs

API Platform documentation

https://api-platform.com/docs/

164 stars 1.06k forks source link

Add an introduction to the concepts API Platform is using #869

Open dunglas opened 4 years ago

dunglas commented 4 years ago

Many newcomers struggle to find the explanation about the architectural style and the standards API Platform is built on. They are - among many others - REST, HTTP, URL/URI/IRI, JSON-LD, Hydra, Schema.org, RDF... It's a lot of architectural concepts and protocols to assimilate.

It could be nice to add a lexicon of with the specs and concepts used by API Platform, with link to the reference documents. Some links:

General Introductions

Architectural Styles and the Design of Network-based Software Architectures: https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
Building JSON-LD APIs: Best Practices: https://json-ld.org/spec/latest/json-ld-api-best-practices/
Cool URIs don't change: https://www.w3.org/Provider/Style/URI

RFC and specs

HTTP(bis): https://tools.ietf.org/html/rfc7231
IRI: https://tools.ietf.org/html/rfc3987
JSON-LD: https://www.w3.org/TR/json-ld/
Hydra: https://www.hydra-cg.com/spec/latest/core/
Schema.org: https://schema.org/docs/documents.html

teohhanhui commented 4 years ago

Didn't know about the "httpbis" thing. This is where to look: https://tools.ietf.org/wg/httpbis/