Logging API Calls

API Calls are one of the two event types that can be logged to Moesif for analysis (the other being custom actions). API Calls are automatically logged when using one of the server integrations for popular API gateways and web frameworks. Once logged to Moesif, the rest of the data processing is handled automatically.

To filter by API Calls in Moesif, select the Event Type filter and then pick API Call. Then, you’ll see your live API logs, as shown below:

Filtering API logs

Default fields

Moesif will automatically analyze various default fields, such as HTTP Headers, body fields, and query parameters. Any of these fields can be used in Moesif’s powerful filtering and aggregations.

Body payloads

Moesif will also provide metrics on payload keys for supported content types. JSON, XML, SOAP, GraphQL, and other text formats are currently supported. Moesif also works with binary formats like ProtoBuf, but you may be missing certain aggregations and metrics related to the body fields.

If you have sensitive data such as financial or healthcare, you can leverage client-side encryption or disable body logging.

Parsing URL-encoded form data

When using URL-encoded form data, pay attention to how you define the key-value pairs.

If the URL-encoded form data has multiple keys, Moesif considers them as arrays for the following formats:

credits_array=1&credits_array=1&credits_array=1&credits_array=1
credit_array[]=1&credit_array[]=1&credit_array[]=1&credit_array[]=1

In both cases, Moesif translates them into the array "credit_array"=>["1", "1", "1", "1"].

For all other formats of URL-encoded data with multiple keys, Moesif processes them as strings rather than arrays:

credit_array=[1,1,1,1]
credit_array=1,1,1,1
credit_array=1%2C1%2C1%2C1
credit_array[0]=1&credit_array[1]=1&credit_array[2]=1&credit_array[3]=1

Event metadata

Besides the default API fields Moesif already analyzes, you can append custom event metadata to any API call. For example, you may want to save tracing information, virtual machine identifiers, or other context variables with an API call.

{
  "some_string": "I am a string",
  "some_int": 77,
  "some_object": {
      "some_sub_field": "some_value"
    }
}

Saving event metadata

Each SDK has a slightly different way to save event metadata, browse your specific server integration for details.

In order to save metadata, override the respective getMetadata() function in your SDK’s options. The SDK’s getMetadata hook will pass in both the request and response object for context, which you can read when setting metadata fields.

For example, the below code will parse the version string from the URI, such as in /api/v1/:items, and also read an environment variable called DATACENTER, which contains the location.

options.getMetadata = function (req, res) {
  let versionRegex = /v\d*/;

  return {
    api_version: versionRegex.match(req.uri)[0],
    datacenter: process.env.DATACENTER
  };
}

Using event metadata

Now that we are tracking custom event metadata, we can create metrics reports within Moesif. For our example above, we can understand which data-center locations are seeing the most API traffic.

To do so, we can select Time Series under the + New button on the left-side navigation. You can open the Metadata within any filter/group by/metric dropdowns.

Group By on Custom Event Fields

In our example, we select metadata.datacenter, now our chart will show the daily API calls broken down by data center region as shown below:

Daily API call volume by datacenter location

Best practices

Follow these best practices when defining event metadata.

Maintain consistent data types

Once a specific JSON key is seen by Moesif with a specific JSON data type, you cannot send a different JSON datatype using the same key. For example, if you previously sent to Moesif the following event metadata for an API call:

{
  "some_string": "I am a string",
  "some_int": 77,
  "some_object": {
      "some_sub_field": "some_value"
    }
}

Then, Moesif automatically saves some_string as a JSON string in the metadata schema. You cannot later send a JSON Number using the same some_string key. This is true regardless of the number of levels relative to the object root. The below metadata would now be invalid:

{
  "some_int": 77,
  "some_object": {
      "some_string": 23,
      "some_sub_field": "some_value"
    }
}

The metadata schema is specific to each application you create in Moesif. For example, your development environment can be different than your prod environment.

Avoid dot characters

Be aware that Dot characters in a JSON key for event metadata will be converted into an underscore by Moesif automatically. However, Dot characters in a JSON value are fine and will not be transformed.

For example,

{
  "so.me_str.ing": "I am a string",
  "some.int": 77.23
}

Will be converted by Moesif to:

{
  "so_me_str_ing": "I am a string",
  "some_int": 77.23
}

Updated: