Skip to content
Snippets Groups Projects
Unverified Commit 2a117579 authored by Patrick Figel's avatar Patrick Figel
Browse files

Improve APIv4 usage docs 

This contains a mix of typo and style fixes, removes some bits that
were copied from APIv3 and adds some missing sections.
parent 5080e861
No related branches found
No related tags found
1 merge request!718Improve APIv4 usage docs
Hide whitespace changes
Inline Side-by-side
Showing
with 58 additions and 34 deletions
docs/api/v4/usage.md
+ 58
− 34
View file @ 2a117579
# APIv4 Usage # APIv4 Usage
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: Every API call consists of three elements: the *entity*, *action*, and *parameters*. Some commonly used entities in CiviCRM include the following:
(*For full, up-to-date details about specific entities and parameters, use the [API Explorer](/api/index.md#api-explorer).*) | Entity | Description |
|------------|--------------------------------------------|
| `Contact` | An individual, organization, or household. |
| `Activity` | A phone call, meeting, or email message. that has occurred (or will occur) at a specific date and time. |
| `Address` | A street-address related to a contact. |
The API is available in many different environments (such as PHP, REST, and Javascript), and the notation differs slightly in each environment. Each entity supports a number of actions. Consider these samples with commonly-used actions and parameters for the `Contact` entity:
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 arrayObject is returned as output. | Action | Parameters | Description |
|----------|--------------------------------------|---------------------------------|
| `create` | `#!json {"values":{"contact_type":"Individual", "first_name":"Jane", "last_name":"Doe"}}` | Create a new contact of type "Individual" with first name "Jane" and last name "Doe" |
| `get` | `#!json {"where":[["last_name", "=", "Doe"]], "limit":25}` | Fetch the first 25 contacts with the last name "Doe" |
| `delete` | `#!json {"where":[["id", "=", 42]]}` | Delete the contact with id "42" |
A couple of significant differences between APIv4 and APIv3 is that in v4 the `check_permissions` flag is set to true by default and on get actions especially but more generally the limit of 25 items returned that v3 has has been removed in favour of coders specifying the limit if they want to in their code calls. (*For full, up-to-date details about specific entities and parameters, use the [API Explorer](/api/index.md#api-explorer).*)
!!! info !!! info
As of CiviCRM version 5,18 not all core entities have been added to APIv4. You should check the API explorer to see which entities are available. If the entity you require is not available then please open a pull request against the [`civicrm-core` repository](https://github.com/civicrm/civicrm-core) to add the entity in or open an (issue)[https://lab.civicrm.org/dev/core] and request that the entity is added. As of CiviCRM version 5.18, not all core entities have been added to APIv4. You should check the API Explorer to see which entities are available. If the entity you require is not available then please open a pull request against the [`civicrm-core` repository](https://github.com/civicrm/civicrm-core) to add the entity or open an [issue](https://lab.civicrm.org/dev/core) and request that the entity is added.
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 `arrayObject` is returned as output.
```php ```php
$result = Civi::service('civi_api_kernel')->run('Contact', 'get', [ $result = Civi::service('civi_api_kernel')->run('Contact', 'get', [
...@@ -26,30 +38,28 @@ $result = Civi::service('civi_api_kernel')->run('Contact', 'get', [ ...@@ -26,30 +38,28 @@ $result = Civi::service('civi_api_kernel')->run('Contact', 'get', [
The result of a successful API call typically looks like this: The result of a successful API call typically looks like this:
```php ```json
[ [
{ /* DAO Object */ } { /* DAO Object */ }
] ]
``` ```
The result of a failed API call typically looks like this: The result of a failed API call typically looks like this:
```php ```json
array( {
'is_error' => 1, "error_code": 0
'error_message' => /* a descriptive error message */, }
)
``` ```
!!! note !!! info
A few specialized actions like `getsingle` or `getvalue` may return success in a different format. Some parts of APIv4 differ significantly from APIv3, including the handling of `check_permissions` and the default limit for returned objects being removed. For details, refer to [Differences Between APIv3 and APIv4](/api/v4/differences-with-v3.md).
## PHP ## PHP
This is the most common way to call the API. There are 2 formats of API calls a procedural approach and the more traditional approach This is the most common way to call the API. There are two formats of API calls: an object-oriented approach and the more traditional procedural style.
Object Oriented Procedural approach: ### Object-Oriented (OOP)
```php ```php
$contacts = \Civi\Api4\Contact::get() $contacts = \Civi\Api4\Contact::get()
...@@ -58,7 +68,11 @@ $contacts = \Civi\Api4\Contact::get() ...@@ -58,7 +68,11 @@ $contacts = \Civi\Api4\Contact::get()
->execute(); ->execute();
``` ```
Note that we use the a format of Object::action and then there are helper functions like AddWhere The API is first invoked using a static method in the form of `#!php Entity::action()`.
The returned object implements a number of helper methods like `#!php addWhere()`.
These helper methods use method chaining, which allows multiple methods to be chained together in one statement as shown above.
### Traditional (Procedural)
```php ```php
try { try {
...@@ -75,26 +89,25 @@ catch (\API_Exception $e) { ...@@ -75,26 +89,25 @@ catch (\API_Exception $e) {
printf("Found %d item(s)\n", count($contacts)); printf("Found %d item(s)\n", count($contacts));
``` ```
This format matches canonical format almost exactly, with a few improvements for usability: This format matches the canonical format almost exactly, with a few improvements for usability:
- The `version => 4` parameter is not required. - The `version => 4` parameter is not required.
- Errors are reported as PHP exceptions. You may catch the exceptions or (by default) allow them to bubble up. - Errors are reported as PHP exceptions. You may catch the exceptions or (by default) allow them to bubble up.
- You can immediately iterate over the contacts returned - You can immediately iterate over the contacts returned.
*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](/framework/bootstrap.md). *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](/framework/bootstrap.md).
## REST ## REST
To be implemented APIv4 is not yet available via REST. This is being tracked in [dev/core#1310](https://lab.civicrm.org/dev/core/issues/1310).
## AJAX ## AJAX
```javascript ```javascript
CRM.api4('entity', 'action', [params], [statusMessage]); CRM.api4('entity', 'action', [params], [index]);
``` ```
If you pass `true` in as the `StatusMessage` param, it will display the default Status Message. This is useful when doing things such as adding tags to contacts or similar. If you wish to do further work based on the result of the API call (e.g use the results from a GET call) you will need to use the [done method](http://api.jquery.com/deferred.done/) to listen for the event. For example: If you wish to do further work based on the result of the API call (e.g use the results from a GET call) you will need to use the [done method](http://api.jquery.com/deferred.done/) to listen for the event. For example:
```javascript ```javascript
CRM.api4('EntityTag', 'create', { CRM.api4('EntityTag', 'create', {
...@@ -108,33 +121,44 @@ CRM.api4('EntityTag', 'create', { ...@@ -108,33 +121,44 @@ CRM.api4('EntityTag', 'create', {
The AJAX interface is automatically available for web-pages generated through CiviCRM (such as standard CiviCRM web-pages, CiviCRM extensions and custom CiviCRM templates). The AJAX interface is automatically available for web-pages generated through CiviCRM (such as standard CiviCRM web-pages, 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()` The AJAX interface could be made available to other parts of the same website (e.g. a Drupal module or WordPress widget) by calling `#!php CRM_Core_Resources::singleton()->addCoreResources()`
from php. Please note that the AJAX interface is subject to [API Security](/security/permissions.md#api-permissions) from PHP. Please note that the AJAX interface is subject to [API Security](/security/permissions.md#api-permissions)
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. 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 ## Smarty
## Scheduled jobs APIv4 is not yet available as a Smarty function.
Any API call can be configured to be run as a scheduled job. These can be configured in the UI under **Administer -> System Settings -> Scheduled Jobs**. Usually API calls run this way are written with the intent that they be run as scheduled jobs - e.g those with the Job entity or provided by payment processors to run recurring payments.
## Scheduled jobs
APIv4 is not yet available for scheduled jobs.
## Command line ## Command line
### drush ### drush
To be Implemented APIv4 is not yet available as a drush command.
### wp-cli ### wp-cli
To be Implemented APIv4 is not yet available as a wp-cli command.
### cv ### cv
`cv` supports multiple input formats for APIv4. The API Explorer uses the JSON format in generated code:
```bash ```bash
cv api4 Contact.get '{"where":[["first_name", "=", "Alice"], ["last_name", "=", "Roberts"]]}' cv api4 Contact.get '{"where":[["first_name", "=", "Alice"], ["last_name", "=", "Roberts"]]}'
``` ```
This format may be cumbersome to enter manually, so the same API request could also be written like this:
```bash
cv api4 Contact.get +w 'first_name = "Alice"' +w 'last_name = "Roberts"'
```
For more examples, refer to the output of `cv --help api4`.
## API Security ## API Security
API has security measures built in depending on the way the API is called that can also be turned off or on. API Permissions are also able to be altered via hook. More information on API Security can be found in the [Security Documentation](/security/permissions.md). API has security measures built in depending on the way the API is called that can also be turned off or on. API Permissions are also able to be altered via hook. More information on API Security can be found in the [Security Documentation](/security/permissions.md).
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment