Creating & incrementing counters

To create a new counter or increment an existing counter, include the counter property in the body of a POST to the /events endpoint. More than one counter can be incremented in the same request.

Note: It may take up to 30 seconds after an event has been posted for the counter to be incremented.

Request syntax

::

    curl -X POST https://api.usergrid.com/<org>/<app>/events -d '{"timestamp":<timestamp>, "counters" : {<counter_name>:<increment_value>}}'

Parameters

+--------------------+---------------------------------------------------------------------------------------+
| Parameter          | Description                                                                           |
+====================+=======================================================================================+
| org                | Organization UUID or organization name                                                |
+--------------------+---------------------------------------------------------------------------------------+
| app                | Application UUID or application name                                                  |
+--------------------+---------------------------------------------------------------------------------------+
| timestamp          | A required UNIX timestamp that specifies the time the counter is being incremented.   |
+--------------------+---------------------------------------------------------------------------------------+
| counter\_name      | The name of the counter to create or the existing counter to increment.               |
+--------------------+---------------------------------------------------------------------------------------+
| increment\_value   | The value to increment the counter by.                                                |
+--------------------+---------------------------------------------------------------------------------------+

Regarding the ``increment_value``, a negative number can be specified to
decrement the value. A value of '0' can be specified to reset the value
of the counter.

For the ``timestamp``, specifying a value of 0 will automatically assign
the current time.

Example request

The following request will increment the ‘button_clicks’ counter by one, with a timestamp of the current time.

::

curl -X POST https://api.usergrid.com/your-org/your-app/events -d '{"timestamp":0, "counters" : {"button_clicks":1}}'

Example response

::

    {
      "action" : "post",
      "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
      "params" : { },
      "path" : "/events",
      "uri" : "https://api.usergrid.com/your-org/your-app/events",
      "entities" : [ {
        "uuid" : "b11217fc-9d3a-1427-b24e-699740088e05",
        "type" : "event",
        "created" : 1401224590293,
        "modified" : 1401224590293,
        "timestamp" : 1401224590293,
        "counters" : {
          "button_clicks" : 1
        },
        "message" : null,
        "metadata" : {
          "path" : "/events/b11217fc-9d3a-1427-b24e-699740088e05"
        }
      } ],
      "timestamp" : 1401224590291,
      "duration" : 30,
      "organization" : "your-org",
      "applicationName" : "your-app"
    }
        

Decrementing/resetting counters
-------------------------------

To decrement a counter, specify a negative number for the counter value
in any of the above examples.

To reset a counter, specify a value of 0 for the counter value in any of
the above examples.

Note that the Usergrid JavaScript SDK also provides dedicated methods
for decrementing and resetting counters.

Using counters hierarchically
-----------------------------

You can organize counters into hierarchies by giving them dot-separated
names, e.g. ``button_clicks.homepage``. Incrementing a counter lower in
a hierarchy increments all of the counters upward in the hierarchy
chain.

For example, you want to log errors that your app generates, so you
create hierarchical counters for each module and function within that
module. In this example, you create the following set of counters:

::

    errors
    errors.module
    errors.module.function

Incrementing ``errors.module.function`` by 1 increments all three
counters by 1. A hierarchy can be a useful way of easily tracking
actions in your app at both a cumulative and granular level.