jsonapi.api.php | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/jsonapi.api.php b/jsonapi.api.php
index 75a6f63..55ef75e 100644
--- a/jsonapi.api.php
+++ b/jsonapi.api.php
@@ -8,6 +8,21 @@
 /**
  * @defgroup jsonapi_normalizer_architecture JSON API Normalizer Architecture
  * @{
+ *
+ * @section resources Resources
+ * The unit of data in the JSON API spec is a "resource". The Drupal module that
+ * implements JSON API exposes every entity as a resource.
+ *
+ * While it is theoretically possible to expose arbitrary data as resources, the
+ * decision to limit to only (config and content) entities means that all
+ * relationships between entities (resources) and entity types (resource types)
+ * are available automatically, without the need for another abstraction layer.
+ *
+ * The JSON API module can be summarized as just that: logic that exposes Drupal
+ * entities according to the JSON API spec.*
+ *
+ *
+ * @section normalizers Normalizers
  * The JSON API module reuses as many of Drupal core's Serialization module's
  * normalizers as possible.
  *
@@ -24,5 +39,29 @@
  *
  * A benefit of implementing normalizers at that lower level is that they then
  * work automatically for both the JSON API module and core's REST module.
+ *
+ *
+ * @section api API
+ * The JSON API module does not provide a PHP API. It is designed to be
+ * "zero-configuration".
+ *
+ * - Adding new resources/resource types is unsupported: all entities/entity
+ *   types are exposed automatically. If you want to expose more data via JSON
+ *   API, make sure they're entities. See the "Resources" section.
+ * - Customizing the normalization of fields is not supported: only normalizers
+ *   for "DataType" plugins are supported (a level below fields).
+ *
+ * The JSON API module only provides a HTTP API, that follows the jsonapi.org
+ * spec.
+ *
+ *
+ * @section bc Backwards Compatibility
+ * PHP API: there is no PHP API, which means this module's implementation
+ * details are free to change at any time.
+ *
+ * HTTP API: bugfixes made to comply better with the jsonapi.org spec are never
+ * considered backwards compatibility breaks. URLs and response structure will
+ * never be changed: backwards compatibility is guaranteed for those.
+ *
  * @}
  */