diff --git a/docs/api/basic.md b/docs/api/basic.md
deleted file mode 100644
index 6086b70fbf850f5aea3815083c795c740f33ed55..0000000000000000000000000000000000000000
--- a/docs/api/basic.md
+++ /dev/null
@@ -1,53 +0,0 @@
-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.
-````
diff --git a/docs/api/binding.md b/docs/api/binding.md
deleted file mode 100644
index 46854e18d064e57539fa61dbd5cf0b54a243afc9..0000000000000000000000000000000000000000
--- a/docs/api/binding.md
+++ /dev/null
@@ -1,175 +0,0 @@
-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.
-
-You can use the API: 
-
-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. 
-
-The following examples show how to search for contacts named "Alice
-Roberts".
-
-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).
-
-```
-try{
-   $contacts = civicrm_api3('contact', 'get', array(
-      'first_name'  =>  'Alice',
-      'last_name'   =>  'Roberts'
-   ));
-}
-catch (CiviCRM_API3_Exception $e) {
-   $error = $e->getMessage();
-}
-printf("Found %d item(s)\n", $contacts['count']);
-
-```
-
-<h3>Errors and Exceptions</h3>
-
-There are two common ways to invoke the procedural API. They are nearly
-identical, except in the handling of the errors:
-
- * `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`.
-
-<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)
-----------------------------
-
-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:
-
-````
-
-require_once 'your/civicrm/folder/api/class.api.php';
-$api = new civicrm_api3();
-$apiParams = array(
-   'first_name'   =>  'Alice',
-   'last_name'    =>  'Roberts'
-);
-if ($api->Contact->Get($apiParams)) {
-   //each key of the result array is an attribute of the api
-    echo "\n contacts found ".$api->count;
-   '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
-specify 'version' as a parameter
-
-REST
-----
-
-````javascript
-
-// For external services
-http://www.example.com/sites/all/modules/civicrm/extern/rest.php
-  ?api_key=t0ps3cr3t
-  &key=an07h3rs3cr3t
-  &json=1
-  &debug=1
-  &version=3
-  &entity=Contact
-  &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
-  &debug=1
-  &version=3
-  &entity=Contact
-  &action=get
-  &first_name=Alice
-  &last_name=Roberts
-
-````
-
-Obviously you should substitute your site in! You can explore the syntax
-and options available using the [api
-explorer](http://sandbox.civicrm.org/civicrm/ajax/doc#explorer) (also on
-your site!)
-
-Please note that the REST interface is subject to [API Security](/confluence/display/CRMDOC/API+Security).
-
-For more details, see [REST
-interface](http://wiki.civicrm.org/confluence/display/CRMDOC/REST+interface). 
-
-AJAX
-----
-
-````
-CRM.api3('entity', 'action', [params], [statusMessage]);
-
-````
-
-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
-------
-
-````
-
-{crmAPI var="myContactList" entity="Contact" action="get" version="3" first_name="Alice" last_name="Roberts" }
-Found {$myContactList.count} item(s).
-
-````
-
-
-The smarty call is to add extra information, therefore *create* or
-*delete* actions don't make sense in this case.
-
-For more details, see [Smarty API
-interface](/confluence/display/CRMDOC/Smarty+API+interface).
-
-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
-
-````
diff --git a/docs/api/usage.md b/docs/api/usage.md
new file mode 100644
index 0000000000000000000000000000000000000000..53c8a85f8f14e6b85bb171d7d8f2520ded694f3b
--- /dev/null
+++ b/docs/api/usage.md
@@ -0,0 +1,207 @@
+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 */,
+)
+```
+
+The result of a failed API call typically looks like this:
+
+````
+array(
+  'is_error' => 1,
+  'error_message' => /* a descriptive error message */,
+)
+````
+
+(**Note**: A few specialized actions like `getsingle` or `getvalue` may
+return success in a different format.)
+
+
+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',
+  ));
+}
+catch (CiviCRM_API3_Exception $e) {
+  $error = $e->getMessage();
+}
+printf("Found %d item(s)\n", $contacts['count']);
+```
+
+This format matches canonical format almost exactly, with a few improvements
+for usability:
+
+ * 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.
+
+*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). 
+
+
+PHP (class.api.php)
+----------------------------
+
+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(
+   'first_name'   =>  'Alice',
+   'last_name'    =>  'Roberts'
+);
+if ($api->Contact->Get($apiParams)) {
+   //each key of the result array is an attribute of the api
+    echo "\n contacts found ".$api->count;
+   '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
+specify 'version' as a parameter
+
+REST
+----
+
+````javascript
+
+// For external services
+http://www.example.com/sites/all/modules/civicrm/extern/rest.php
+  ?api_key=t0ps3cr3t
+  &key=an07h3rs3cr3t
+  &json=1
+  &debug=1
+  &version=3
+  &entity=Contact
+  &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
+  &debug=1
+  &version=3
+  &entity=Contact
+  &action=get
+  &first_name=Alice
+  &last_name=Roberts
+
+````
+
+Obviously you should substitute your site in! You can explore the syntax
+and options available using the [api
+explorer](http://sandbox.civicrm.org/civicrm/ajax/doc#explorer) (also on
+your site!)
+
+Please note that the REST interface is subject to [API Security](/confluence/display/CRMDOC/API+Security).
+
+For more details, see [REST
+interface](http://wiki.civicrm.org/confluence/display/CRMDOC/REST+interface). 
+
+AJAX
+----
+
+````
+CRM.api3('entity', 'action', [params], [statusMessage]);
+
+````
+
+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
+------
+
+````
+
+{crmAPI var="myContactList" entity="Contact" action="get" version="3" first_name="Alice" last_name="Roberts" }
+Found {$myContactList.count} item(s).
+
+````
+
+
+The smarty call is to add extra information, therefore *create* or
+*delete* actions don't make sense in this case.
+
+For more details, see [Smarty API
+interface](/confluence/display/CRMDOC/Smarty+API+interface).
+
+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
+````
diff --git a/mkdocs.yml b/mkdocs.yml
index e9e139f15447bb61b56e4b9c0e339fd53c81a7dc..170a745756745ad9e5124fdbf1622a47927b0379 100644
--- a/mkdocs.yml
+++ b/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