Initial documentation of entity configuration (#55103)

Co-authored-by: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>

packages/core-data/README.md

@@ -40,6 +40,65 @@ function MyAuthorsListBase() {
 }
 ```
 
+## What's an entity?
+
+An entity represents a data source. Each item within the entity is called an entity record. Available entities are defined in `rootEntitiesConfig` at ./src/entities.js.
+
+As of right now, the default entities defined by this package map to the [REST API handbook](https://developer.wordpress.org/rest-api/reference/), though there is nothing in the design that prevents it from being used to interact with any other API.
+
+What follows is a description of some of the properties of `rootEntitiesConfig`.
+
+## baseURL
+
+-   Type: string.
+-   Example: `'/wp/v2/users'`.
+
+This property maps the entity to a given endpoint, taking its relative URL as value.
+
+## baseURLParams
+
+-   Type: `object`.
+-   Example: `{ context: 'edit' }`.
+
+Additional parameters to the request, added as a query string. Each property will be converted into a field/value pair. For example, given the `baseURL: '/wp/v2/users'` and the `baseURLParams: { context: 'edit' }` the URL would be `/wp/v2/users?context=edit`.
+
+## key
+
+-   Type: `string`.
+-   Example: `'slug'`.
+
+The entity engine aims to convert the API response into a number of entity records. Responses can come in different shapes, which are processed differently.
+
+Responses that represent a single object map to a single entity record. For example:
+
+```json
+{
+	"title": "...",
+	"description": "...",
+	"...": "..."
+}
+```
+
+Responses that represent a collection shaped as an array, map to as many entity records as elements of the array. For example:
+
+```json
+[
+	{ "id": 1, "name": "...", "...": "..." },
+	{ "id": 2, "name": "...", "...": "..." },
+	{ "id": 3, "name": "...", "...": "..." }
+]
+```
+
+There are also cases in which a response represents a collection shaped as an object, whose key is one of the property's values. Each of the nested objects should be its own entity record. For this case not to be confused with single object/entities, the entity configuration must provide the property key that holds the value acting as the object key. In the following example, the `slug` property's value is acting as the object key, hence the entity config must declare `key: 'slug'` for each nested object to be processed as an individual entity record:
+
+```json
+{
+	"publish": { "slug": "publish", "name": "Published", "...": "..." },
+	"draft": { "slug": "draft", "name": "Draft", "...": "..." },
+	"future": { "slug": "future", "name": "Future", "...": "..." }
+}
+```
+
 ## Actions
 
 The following set of dispatching action creators are available on the object returned by `wp.data.dispatch( 'core' )`: