Edits to APIv4 section

docs/api/index.md

@@ -21,7 +21,7 @@ The API explorer is a powerful GUI tool for building and executing API calls. To
 2. Within the CivCRM menu, go to **Support > Developer** and either **API Explorer v3** or **API Explorer v4** (URL `/civicrm/api` or `/civicrm/api4`).
 
 !!! warning
-    The API explorer actually executes real API calls. It can modify data! So if you execute a `Contact` `delete` call, it will really delete the contact. As such, any experimenting is best done within a test site.
+    The API explorer executes real API calls. It can modify data! So if you execute a `Contact` `delete` call, it will really delete the contact. As such, any experimenting is best done within a test site.
 
 You can select the entity you want to use, for example `Contact` and the action you want to perform, for example `Get`. The API explorer will show you the specific code necessary to execute the API call you have been testing using the various API interfaces available.
 

docs/api/v4/actions.md

 # APIv4 Actions
 
-Most entities support the following actions:
+*Most entities support the following actions:*
+
+## Get
+
+Search for records based on query parameters.
 
 ## Create
 
@@ -8,27 +12,25 @@ Insert new records into the database.
 
 ## Update
 
-Update records in the database.
+Update one or more records in the database based on query parameters.
 
-## Delete
+## Save
 
-Delete one or more records. Requires an explicit `id`. If you want to skip the 'recycle bin' for entities that support undelete (e.g. contacts) you should set `$param['skip_undelete'] => 1);`
+Create or update one or more records. Passing an `id` determines that an existing record will be updated.
 
-## Get
+## Replace
 
-Search for records
+Replace an existing set of records with a new or modified set of records. For example, replace a group of "Phone" numbers for a given contact.
 
-## GetFields
+!!! warning
+    Replace includes an implicit delete action - use with care & test well before using in production.
 
-Fetch entity metadata, i.e. the list of fields supported by the entity. There is now an option that you can pass in for get fields which is `loadOptions`. This is the equivilant of the apiv3 getoptions API call. When used for any field that specifies a pseudoconstant it will return the relevant options in an options key. You can also pass in an option `IncludeCustom` which will specifiy whether to include the relevant custom fields for that entity or not.
+## Delete
 
-## Replace
+Delete one or more records based on query parameters.
 
-Replace an old set of records with a new or modified set of records. (For example, replace the set of "Phone" numbers with a different set of "Phone" numbers.).
+## GetFields
 
-!!! warning
-    Replace includes an implicit delete action - use with care & test well before using in production.
+Fetch entity metadata, i.e. the list of fields supported by the entity. Optionally include custom fields; optionally load the option-lists for fields.
 
-## Save
 
-Create or update one or more records

docs/api/v4/chaining.md

 # APIv4 Chaining
 
-It is possible to do two API calls at once with the first call feeding into the second. E.g. to create a contact with a contribution you can nest the contribution create into the contact create. Once the contact has been created it will action the contribution create using the id from the contact create as `contact_id`. Likewise you can ask for all activities or all contributions to be returned when you do a `get`.
+Chaining lets you perform multiple API calls at once with the first call feeding into the second. E.g. to create a contact with a contribution you can nest the contribution create into the contact create. Likewise you can ask for all activities or all contributions to be returned when you do a `get`.
 
-Note that there are a few supported syntaxes:
+## Supported Syntaxes:
 
 Object Oriented way
 
@@ -29,7 +29,7 @@ civicrm_api('Contact', 'create', [
 ]);
 ```
 
-If you have 2 websites to create you can pass them as separate key => array pairs just specify a unique array key in the chain array
+If you have 2 websites to create you can pass them as separate key => array pairs just specify a unique array key in the chain array.
 
 Object Oriented way
 
@@ -52,10 +52,12 @@ civicrm_api('Contact', 'create', [
     'display_name' => 'BA Baracus',
   ],
   'chain' => [
-    'create_first website', ['Website', 'create', ['values' => ['url' => 'example1.com', 'contact_id' => '$id']]],
-    'create_second_website', ['Website', 'create', ['values' => ['url' => 'example2.com', 'contact_id' => '$id']]],
+    'first website', ['Website', 'create', ['values' => ['url' => 'example1.com', 'contact_id' => '$id']]],
+    'second_website', ['Website', 'create', ['values' => ['url' => 'example2.com', 'contact_id' => '$id']]],
   ],
 ]);
 ```
 
-Note the use of "$id" in the examples above - any field returned by the outer call can be passed down to a chained call by prefixing it with a dollar sign. Even the results of other chains can be accessed in this way.
+## Back-references
+
+Note the use of '$id' in the examples above. Any field returned by the outer call can be passed down to a chained call by prefixing it with a dollar sign. Even the results of other chains can be accessed in this way.

docs/api/v4/custom-data.md

 # APIv4 and Custom Data
 
-CiviCRM has a flexible custom data system which allows nearly any entity to be extended. It comes in two distinct flavors: Single-record and Multi-record. For more background see the user guide chapter: [Creating Custom Fields](https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/).
+CiviCRM has a flexible custom data system which allows nearly any entity to be extended. It comes in two distinct flavors: Single-record and Multi-record.
+For more background see the user guide chapter: [Creating Custom Fields](https://docs.civicrm.org/user/en/latest/organising-your-data/creating-custom-fields/).
 
 ## Single-Record Custom Data
 
-Because single-record fields extend an entity 1-to-1, the API treats the custom fields as an extension of the regular fields. For example, normally an Event has fields like `id`, `title`, `start_date`, `end_date`, etc. Adding a custom group named "Event_Extra" and a field named "Room_number" would be accessible from the API as "Event_Extra.Room_number". You would retrieve it and set it as if it were any other field. Note that the `name` of a field is not to be confused with the `label` The API refers to custom groups/fields by name and not user-facing labels which are subject to translation and alteration.
+Because single-record fields extend an entity 1-to-1, the API treats the custom fields as an extension of the regular fields.
+For example, normally an Event has fields like `id`, `title`, `start_date`, `end_date`, etc.
+Adding a custom group named "Event_Extra" and a field named "Room_number" would be accessible from the API as "Event_Extra.Room_number".
+You would retrieve it and set it as if it were any other field.
+ 
+!!! tip
+    The `name` of a field is not to be confused with the `label`. The API refers to custom groups/fields by name and not user-facing labels which are subject to translation and alteration.
 
 ## Multi-Record Custom Data
 
@@ -41,4 +48,7 @@ New custom fields can be configured to store different types of data (Text, Date
 
 ## Try It Out
 
-Once you have created some custom data in your system, look for it in the API Explorer. Single-record data will appear as fields on the entities they extend, and multi-record data will appear in the list of entities (look under "C" alphabetically as they all start with the prefix "Custom_".
+Once you have created some custom data in your system, look for it in the API Explorer. Single-record data will appear as fields on the entities they extend, and multi-record data will appear in the list of entities.
+
+!!! tip
+    In the Api Explorer look for your multi-record custom entities under "C" alphabetically as they all start with the prefix "Custom_".

docs/api/v4/differences-with-v3.md

@@ -83,10 +83,10 @@ them, it may help to have a concrete example expressed in both APIv3 and APIv4:
     * Object-oriented style: `\Civi\Api4\Entity::action()->...->execute()`
 * When using OOP style in an IDE, most actions and parameters can benefit from auto-completion and type-checking.
 * `$checkPermissions` always defaults to `TRUE`. In APIv3, the default depended on the environment (`TRUE` in REST/Javascript; `FALSE` in PHP).
-* A 4th param `index` controls how results are returned:
+* Instead of APIv3's `sequenaial` param, a more flexible `index` controls how results are returned. In traditional style is is the 4th parameter to the api function:
     * Passing a string will index all results by that key e.g. `civicrm_api4('Contact', 'get', $params, 'id')` will index by id.
     * Passing a number will return the result at that index e.g. `civicrm_api4('Contact', 'get', $params, 0)` will return the first result and is the same as `\Civi\Api4\Contact::get()->execute()->first()`. `-1` is the equivalent of `$result->last()`.
-* When chaining API calls together, back-references to values from the main API call must be explicitly given (discoverable in the API Explorer).
+* When [chaining](/api/v4/chaining.md) API calls together, back-references to values from the main API call must be explicitly given (discoverable in the API Explorer).
 
 ## Actions 
 * For `Get`, the default `limit` has changed. If you send an API call without an explicit limit, then it will return *all* records. (In v3, it would silently apply a default of 25.) However, if you use the API Explorer, it will *recommend* a default limit of 25.
@@ -99,24 +99,22 @@ them, it may help to have a concrete example expressed in both APIv3 and APIv4:
 ## Output  
 * Output is an object (`Result` aka [`ArrayObject`](https://www.php.net/manual/en/class.arrayobject.php)) rather than a plain `array`.
 * In PHP, you can iterate over the `ArrayObject` (`foreach ($myResult as $record)`), or you can call methods like `$result->first()` or `$result->indexBy('foo')`.
-* By default, results are indexed sequentially (`0,1,2,3,...` - like APIv3's `sequential => 1`). You may optionally index by `id`, `name`, or any other field, as in:
+* By default, results are indexed sequentially (`0,1,2,3,...` like APIv3's `sequential => 1`). You may optionally index by `id`, `name`, or any other field, as in:
     * (Procedural-style; use `$index` parameter): `civicrm_api4('Contact', 'get', [], 'id')`
     * (OOP-style; use `indexBy()` method): `\Civi\Api4\Contact::get()->execute()->indexBy('id')`
-
-## Input
-* Instead of a single `$params` array containing a mishmash of fields, options and parameters, each APIv4 parameter is distinct (see section on Params below).
 * Custom fields are refered to by name rather than id. E.g. use `constituent_information.Most_Important_Issue` instead of `custom_4`.
 
-## Params
+## Input
+APIv4 reflects the ongoing efforts present through the lifecycle of APIv3 toward uniform and discreet input parameters.
 
-If you used early versions of APIv3, you might have written some code like this:
+For a little history... If you used early versions of APIv3, you might have written some code like this:
 
 ```php
 civicrm_api3('Contact', 'get', array(
   'check_permissions' => 0,
   'first_name' => 'Elizabeth',
   'return' => 'id,display_name',
-  'rowCount' => 2,
+  'rowCount' => 1000,
   'offset' => 2,
 ));
 ```
@@ -154,7 +152,7 @@ civicrm_api4('Contact', 'get', [
   'checkPermissions' => FALSE,
   'where' => [['first_name', '=', 'Elizabeth']],
   'select' => ['id', 'display_name'],
-  'limit' => 2,
+  'limit' => 1000,
   'offset' => 2,
 ]);
 ```
@@ -162,5 +160,5 @@ civicrm_api4('Contact', 'get', [
 Key things to note:
 
 * The `options` array is completely gone. The params array *is* the list of options.
-* Most of the options in the params array have shared/generic implementations - ensuring consistent naming and behavior.
+* Most of the options in the params array have shared/generic implementations - ensuring consistent naming and behavior for every api entity.
 * The *data* fields (e.g. `id`, `display_name`, and `first_name`) no longer appear at the top. They always appear beneath some other option, such as `where` or `select`.