docs/api - Recombine and reintroduce the basic usage and bindings

docs/api/basic.md

-Every API call consists of three elements:
-
--   **Entity name**: a string such as "Contact" or "Activity"
--   **Action name**: a string such as "create" or "delete"
--   **Parameters**: an associative-array (such as the first-name and
-    last-name of a new contact record); this varies depending on the
-    entity name
-
-Entities
-========
-
-There are many entities supported by the CiviCRM API, and the list
-expands in every release. For current details in your version, see the
-"Documentation" section; in particular, see the "API Explorer" and the
-API examples.
-
-For demonstration, consider a few commonly-used entities:
-
-
-| Entity                   | Description              | Example Parameters       |
-|--------------------------|--------------------------|--------------------------|
-| Contact                  | An individual, <br /> organization, or <br />house-hold.         | “contact\_type”,<br /> “first\_name”,  <br />“last\_name”, <br />“preferred\_language”       |
-| Activity                 | An phone call, meeting,<br /> or email message. that <br /> has occurred (or will <br /> occur) at a specific <br /> date and time| “activity\_type\_id”, <br /> “source\_contact\_id”, <br /> “assignee\_contact\_id”    |
-| Address                  | A street-address related <br /> to a contact. | “contact\_id”,  <br /> “street\_address”, <br /> “city”,  <br /> “state\_province\_id”, <br /> "country\_id’     |
-
-
-
-
-Response Format
-===============
-
-The response from an API call is always an associative-array. The
-response format can vary depending on the action, but generally
-responses meet one of these two structures:
-
-<h3>Success</h3>
-
-````
-$result['is_error'] = 0
-$result['version'] = 2 or 3 as appropriate
-$result['count'] = number of records in the 'values' element of the $result array
-$result['values'] = an array of records
-````
-
-Please note that the **getsingle** response will not have a $result['values'] holding the records, but a $result array with the fields from the selected record. The response $result will only have an  'is\_error' attribute if there actually is an error.
-
-
-<h3>Error</h3>
-
-````
-$result['is_error'] = 1
-$result['error_message'] = An error message as a string.
-````

docs/api/binding.md → docs/api/usage.md

-There are at least 5 different ways of using an API function. In each
-environment, the API uses the same names for entities, actions, and
-parameters, but the syntax is slightly different. Entities are the data
-collections you want to operate on, for example Contact, Event or Group.
-The actions are the thing you want to do to the entity, for example get,
-create, delete or update.
+Every API call consists of three elements: the *entity*, *action*, and
+*parameters*.  For example, consider a few commonly-used entities along
+with the supported actions and parameters:
+
+
+| Entity                   | Description              | Actions |  Parameters       |
+|--------------------------|--------------------------|---------|-------------------|
+| <code>Contact</code>     | An individual, <br /> organization, or <br />house-hold.         |<code>create</code><br/><code>get</code><br/><code>delete</code><br/>| <code>contact\_type</code><br /> <code>first\_name</code>  <br /><code>last\_name</code> <br /><code>preferred\_language</code>       |
+| <code>Activity</code>    | An phone call, meeting,<br /> or email message. that <br /> has occurred (or will <br /> occur) at a specific <br /> date and time|<code>create</code><br/><code>get</code><br/><code>delete</code><br/>| <code>activity\_type\_id</code> <br /> <code>source\_contact\_id</code> <br /> <code>assignee\_contact\_id</code>    |
+| <code>Address</code>     | A street-address related <br /> to a contact. |<code>create</code><br/><code>get</code><br/><code>delete</code><br/>| <code>contact\_id</code>,  <br /> <code>street\_address</code> <br /> <code>city</code>  <br /> <code>state\_province\_id</code> <br /> <code>country\_id</code>     |
+
+(*For full, up-to-date details about specific entities and parameters, use the "API Explorer".*)
+
+The API is available in many different environments (such as PHP, REST, and
+Javascript), and the notation differs slightly in each environment.
+However, if you understand the canonical notation, then other environments
+will appear as small adaptations.
+
+Canonically, an API call is processed by the API kernel.  The `$entity`,
+`$action`, and `$params` are passed as inputs, and an associative-array is
+returned as output.
+
+```php
+$result = Civi::service('civi_api_kernel')->run('Contact', 'get', array(
+  'version' => 3,
+  'first_name' => 'Alice',
+  'last_name' => 'Roberts'
+));
+```
+
+The result of a successful API call typically looks like this:
+
+```php
+array(
+  'is_error' => 0,
+  'version' => 3,
+  'count' => /* number of records */,
+  'values' => /* array of records */,
+)
+```
 
-You can use the API: 
+The result of a failed API call typically looks like this:
 
-1.  as a PHP function, to run your own code on the same server as
-    CiviCRM 
-2.  via the AJAX interface, to be called from JavaScript code
-3.  via the REST\* interface, can be called from another server via
-    http/https calls
-4.  as a Smarty function to add data to templates 
-5.  from drush on the command line for Drupal installations. 
+````
+array(
+  'is_error' => 1,
+  'error_message' => /* a descriptive error message */,
+)
+````
 
-The following examples show how to search for contacts named "Alice
-Roberts".
+(**Note**: A few specialized actions like `getsingle` or `getvalue` may
+return success in a different format.)
 
-PHP (Procedural)
-----------------------
 
-The PHP procedural API is the canonical API – every other API builds on
-top of it. It can be used when writing core code, native extensions
-(modules), or CMS extensions (modules).
+PHP (civicrm_api3)
+------------------
+
+This is the most common way to call the API.
 
 ```
-try{
-   $contacts = civicrm_api3('contact', 'get', array(
-      'first_name'  =>  'Alice',
-      'last_name'   =>  'Roberts'
-   ));
+try {
+  $contacts = civicrm_api3('contact', 'get', array(
+    'first_name'  =>  'Alice',
+    'last_name'   =>  'Roberts',
+  ));
 }
 catch (CiviCRM_API3_Exception $e) {
-   $error = $e->getMessage();
+  $error = $e->getMessage();
 }
 printf("Found %d item(s)\n", $contacts['count']);
-
 ```
 
-<h3>Errors and Exceptions</h3>
+This format matches canonical format almost exactly, with a few improvements
+for usability:
 
-There are two common ways to invoke the procedural API. They are nearly
-identical, except in the handling of the errors:
+ * The function `civicrm_api3()` is easier to remember.
+ * The `version => 3` parameter is not required.
+ * Errors are reported as PHP exceptions. You may catch the exceptions or (by default) allow
+   them to bubble up.
 
- * `civicrm_api3($entity, $action, $params)`: This is the most common
-   approach. If the API call encounters an error, then
-   it will throw a PHP exception. It is recommended for most use cases
-   (application logic, form logic, data-integrations, etc).
- * `civicrm_api($entity, $action, $params)`: This is the older and
-   less common approach, and it is useful for implementing generic
-   bindings (such as REST, SOAP, AJAX, Smarty, etal). Instead of
-   throwing an exception, it returns an array with the properties
-   `is_error` and `error_message`.
+*Note*: If you're writing a Drupal module, a Joomla extension, a WordPress
+plugin, or a standalone script, then you may need to **bootstrap** CiviCRM
+before using the API.  See the examples in [Bootstrap
+Reference](/confluence/display/CRMDOC/Bootstrap+Reference). 
 
-<h3>Bootstrap</h3>
 
-Before calling the PHP procedural API, one may need to ***bootstrap*** CiviCRM. If you're writing code for CiviCRM Core or for a native CiviCRM extension, then the bootstrap is handled automatically. If you're writing code for a Drupal module, a Joomla extension, or a standalone script, then see the examples in [Bootstrap Reference](/confluence/display/CRMDOC/Bootstrap+Reference). 
-
-
-PHP (Object Oriented Client)
+PHP (class.api.php)
 ----------------------------
 
-In CiviCRM version 3.4 an API class was introduced, allowing you to call
-the CiviCRM API in an Object Oriented way. The class is called
-*class.api.php* and can be found in the api directory. It allows you to
-call the API like this:
-
-````
+CiviCRM v3.4 introduced an object-oriented API client, `class.api.php`.
+This class be used locally or remotely to invoke APIs, as in:
 
+```php
 require_once 'your/civicrm/folder/api/class.api.php';
 $api = new civicrm_api3();
 $apiParams = array(
@@ -81,10 +103,8 @@ if ($api->Contact->Get($apiParams)) {
    'contact_type'=>'Individual','return'=>'sort_name,current_employer')) {
 } else {
     echo $api->errorMsg();
-} 
-
-
-````
+}
+```
  
 
 If you call the API in the object oriented fashion, you do not have to
@@ -106,7 +126,7 @@ http://www.example.com/sites/all/modules/civicrm/extern/rest.php
   &action=get
   &first_name=Alice
   &last_name=Roberts
- 
+
 // For sessions already authenticated by the CMS (e.g. AJAX)
 http://www.example.com/civicrm/ajax/rest
   ?json=1
@@ -141,7 +161,7 @@ For more details, see [AJAX
 Interface](/confluence/display/CRMDOC/AJAX+Interface).
 
 The AJAX interface is automatically available for web-pages generated through CiviCRM (such as ***standard CiviCRM web-page****s***, CiviCRM ***extensions***, and custom CiviCRM ***templates***).
-                                                            
+
 The AJAX interface could be made available to other parts of the same website (e.g. a drupal module or wordpress widget) by calling CRM\_Core\_Resources::singleton()-\>addCoreResources() from php. Please note that the AJAX interface is subject to [API Security](/confluence/display/CRMDOC/API+Security) and [Same Origin Policy](http://en.wikipedia.org/wiki/Same_origin_policy). To use it from an external site or application, see REST interface documentation.
 
 Smarty
@@ -161,15 +181,27 @@ The smarty call is to add extra information, therefore *create* or
 For more details, see [Smarty API
 interface](/confluence/display/CRMDOC/Smarty+API+interface).
 
-Drush
+CLI (drush)
 -----
 
-````
-
+```
 ## To run on the default Drupal site
 drush civicrm-api contact.get first_name=Alice last_name=Roberts
- 
+
 ## To run on Drupal multisite, specify the site name
 drush -l www.example.com civicrm-api contact.get first_name=Alice last_name=Roberts
+```
 
+CLI (wp-cli)
+-----
+
+```
+wp civicrm-api contact.get first_name=Alice last_name=Roberts
+```
+
+CLI (cv)
+-----
+
+````
+cv api contact.get first_name=Alice last_name=Roberts
 ````

mkdocs.yml

@@ -11,8 +11,7 @@ pages:
    - Testing: testing.md
  - 'Reference: APIv3':
    - General: api/general.md
-   - 'Basic Usage': api/basic.md
-   - Bindings: api/binding.md
+   - 'Usage': api/usage.md
    - Actions: api/actions.md
    - Parameters: api/params.md
    - Chaining: api/chaining.md