Merge pull request #542 from aydun/master

Update info on civix generate:api

docs/api/index.md

@@ -17,6 +17,7 @@ BAO arguments inevitably occur.
 The best place to begin working with the API is your own ***test*** install of
 CiviCRM, using the API explorer and the API parameter list.
 
+For help creating your own API custom calls, see [civix generate:api](/extensions/civix.md#generate-api)
 
 ## API explorer
 

docs/extensions/civix.md

@@ -426,7 +426,7 @@ See this (somewhat outdated) [wiki page](https://wiki.civicrm.org/confluence/dis
 
 ### Add an API function {:#generate-api}
 
-The [CiviCRM API](/api/index.md) provides a way to expose functions for use by other developers. API functions allow implementing AJAX interfaces (using the cj().crmAPI() helper), and they can also be called via REST, PHP, Smarty, Drush CLI, and more. Each API requires a two-part name: an entity name (such as "Contact", "Event", or "MyEntity") and an action name (such as "Create" or "MyAction").
+The [CiviCRM API](/api/index.md) provides a way to expose functions for use by other developers. API functions allow implementing AJAX interfaces (using the CRM.$().crmAPI() helper), and they can also be called via REST, PHP, Smarty, Drush CLI, and more. Each API requires a two-part name: an entity name (such as "Contact", "Event", or "MyEntity") and an action name (such as "create" or "myaction").
 
 Get started by accessing the `civix` help:
 
@@ -437,19 +437,30 @@ civix help generate:api
 !!! note
     Action names must be lowercase. The javascript helpers `CRM.api()` and `CRM.api3()` force actions to be lowercase. This issue does not present itself in the API Explorer or when the api action is called via PHP, REST, or SMARTY.
 
+!!! note
+    The API loader is very sensitive to case on some platforms.  Be careful with capitalization, underscores and multiword action names.  API calls can work in one context (Mac OSX filesystem, case-insensitive) and fail in another (Linux filesystem, case-sensitive).
+
 You can make your API code with a command in this pattern:
 
 ```bash
-civix generate:api NewEntity NewAction
+civix generate:api NewEntity newaction
 ```
 
 This creates one file:
 
--   `api/v3/NewEntity/NewAction.php` provides the API function.  Note that the parameters and return values must be processed in a particular way (as demonstrated by the auto-generated file).
+-   `api/v3/NewEntity/Newaction.php` provides the API function `civicrm_api3_new_entity_newaction()` and the specification function `_civicrm_api3_new_entity_newaction_spec()`.  Note that the parameters and return values must be processed in a particular way (as demonstrated by the auto-generated file).
+
+For use with CiviCRM 4.3 and later, you can also add the `--schedule` option (e.g., `--schedule Hourly`). This will create another file:
+
+-   `api/v3/NewEntity/Newaction.mgd.php` provides the scheduling record that will appear in the CiviCRM's job-manager.
+
+When calling the API, follow these rules:
 
-For use with CiviCRM 4.3 and later, you can also add the `–schedule` option (e.g., `–schedule Hourly`). This will create another file: 
+-    Entity-names are UpperCamelCase
+-    Action-names are lowersmashedcase
+-    Other variations may work when you call them. Some docs/explorers may show these in cases which work. However, if you try to do the same in new code, you may get a headache.
 
--   `api/v3/NewEntity/NewAction.mgd.php` provides the scheduling record that will appear in the CiviCRM's job-manager.
+For example: `cv api NewEntity.newaction`  `civicrm_api3('NewEntity', 'newaction')`
     
 !!! tip
     Read more about the [API architecture](/framework/api-architecture.md) for help writing your custom API.