Information for: DEVELOPERS   PARTNERS

Graph API: Listen adaptor

The Acquia Journey Graph API listener makes it easy to integrate business logic into other systems by providing a listener adaptor that can be added to any graph to make it publicly accessible by a unique permanent URL.

The Acquia Journey Graph API listener has three modes of operation:

  • Standard API Listener - Exposes a web service endpoint that responds to a web service POST request
  • Web Tracking and Recommendation - Embeds JavaScript, and is available for legacy purposes only. For tracking, use Acquia Lift Profile Manager instead.
  • Pixel Tracking - Embeds a one pixel by one pixel (1x1) transparent image — no cookie is set

The Graph API supports several design patterns, including the following:

  • Each graph as its own micro-service, handling one operation
  • A single graph as the entry point for multiple operations, using an op query parameter and then subgraphs for handing each of the different operations

When implementing a single graph as an entry point for multiple operations, you are creating an API endpoint that offers multiple operations. You can implement this approach using JSON-RPC for structured JSON payloads. The operation performed should be determined by the op query parameter, and each operation should be a function call that, optionally, returns a value.

You can pass data to your operations by using query string parameters for GET requests, or by using the request body for a POST request. You should use POST requests when sending sensitive or identifying information, rather than including the information in the query string of a GET request.

For information about other listener types and their functions, see Acquia Journey adaptors.

Adding a Graph API listener

You can add a new graph API listener by completing the following steps:

  1. Sign in to Acquia Journey.

  2. From the projects list, identify the project you want to create an adaptor for, and click its title. Acquia Journey will display the Overview tab for your project.

  3. Click the Graphs tab.

  4. In the Graphs section, click the name of the graph you want to open.

  5. In the top right corner of the graph editing canvas, click Add Listener. Acquia Journey will display the Listener Editor dialog box.

  6. In the Listener Type select list, click API.

  7. (optional) In the Environment select list, select an environment. To learn more, read Creating and managing environments.

  8. Click Standard or Pixel Tracking to display configuration information for those types of listeners. For more information, see Standard API Listener and Pixel tracking API listener.

    Web Tracking and Recommendation API listener

    Acquia recommends that you use the Acquia Lift Profile Manager for tracking webpage activity.

  9. Copy the appropriate code for your listener into the application of your choice.

  10. Click Save.

The Listener ID is a unique 32-character alphanumeric string that identifies this listener. The same graph API listener in a different environment will have a different Listener ID.

Standard API listener

The standard listener accepts data sent by either a GET or POST request, and returns the value from the Return node on your graph.

Create an API listener

The web service endpoint for the Standard API Listener is displayed in the example as the Endpoint, and is accessible when the graph is running. Any data provided as part of the GET or POST request is placed into the schema variable location selected in the Output location. The API listener adds the special _kw key to the Output location with an object containing the following keys:

  • Headers - the HTTP headers associated with the HTTP request
  • Method - the HTTP method associated with the HTTP request

You can also create micro web services with a standard listener that can be used by external systems. Acquia Journey Graph API supports HTTP GET and HTTP POST methods:

  • POST - the POST body, if any, is saved to the Output location, and any query parameters in the URL will be ignored. The Content-Type may be either application/json or application/xml. The maximum payload size is 100 KB.
  • GET - the URL parameters, if any, are saved to the Output location

Making a GET request

In the following example, the curl command is used to make a HTTP GET request to the API endpoint. The key1 parameter in the query string is assigned the value val. Replace {listenerID} with your API Listener endpoint ID.

curl https://api.journey.acquia.com/api/v1/listener/{listenerID}?key1=val

Making a POST request

The following example describes how to make an HTTP POST request to the API using the curl command. The Acquia Journey Graph API requires the Content-Type header field to be set to either application/json or application/xml when performing a POST operation. Replace {listenerID} with your API Listener endpoint ID.

Note

You must specify the Content-Type when making requests to the API. Most HTTP clients do not use Content-Type: application/json or Content-Type: application/xml as the default. If the Content-Type header is omitted, you will receive an error.

curl -H "Content-Type: application/json" -X POST \
   -d '{"body":"this is my body"}' https://api.journey.acquia.com/api/v1/listener/{listenerID}

If you use application/xml, Acquia Journey performs the following conversions on your XML document before saving it to your Output location:

  • XML elements become JSON arrays
  • XML attributes become $ objects with fields
  • XML body text becomes _ when there are attributes
  • All element names are converted to lowercase
  • Attribute names remain unchanged

XML conversion examples

The following example shows an empty element produces an object with an empty field value:

XML document Output
<xml/>
{
  "xml" : ""
}

The following example shows an empty child element is turned into an array value with a single empty value:

XML document Output
<xml>
<element/>
</xml>
{
  "xml": {
    "element": [
      ""
    ]
  }
}

The following example shows a collection of child elements with simple values is transformed into an array of values:

XML document Output
<xml>
  <element>a</element>
  <element>b</element>
  <element>c</element>
</xml>
{
  "xml": {
    "element": [
      "a",
      "b",
      "c"
    ]
  }
}

The following example shows a collection of child elements with attributes and simple or non-existent values transformed to an array of objects.
An element’s attributes are held in the special “$” attribute of the object they refer to.

XML document Output
<xml>
  <element attr1="a" attr2="b">first element</element>
  <element>second element</element>
  <element/>
</xml>
{
  "xml": {
    "element": [
      {
        "$": {
          "attr2": "b",
          "attr1": "a"
        },
        "_": "first element"
      },
      "second element",
      ""
    ]
  }
}

In the following example, the attribute names are not converted to lowercase:

XML document Output
<xml>
  <element attr1="a" AttributeTwo="b">first element</element>
  <element>second element</element>
  <element/>
</xml>
{
  "xml": {
    "element": [
      {
        "$": {
          "AttributeTwo": "b",
          "attr1": "a"
        },
        "_": "first element"
      },
      "second element",
      ""
    ]
  }
}

If the XML is invalid, as in the following example, Acquia Journey provides the location of the error in the message property:

XML document Output
<xml>
  <element attr1="a" attr2="b">f
    irst element
  </element2>
  <element>second element</element>
  <element/>
</xml>
{
  "message": "Unexpected close tag\nLine: 1\nColumn: 55\nChar: >",
  "error": {

  }
}

The following table describes errors that may be returned as a result of an invalid HTTP POST request:

Graph status Error
Deployed graph {"message":"undefined is not a function","error":{}}
Graph being visually tested in the testing console {"message":"req.msgBody.hasOwnProperty is not a function","error":{}}

Sample Web Service endpoint

The following example is an approach for implementing a basic CRUD (create, read, update, and delete) endpoint using the Acquia Journey Graph API:

Operation HTTP Method URL Description
Create POST ?op=create Receives the HTTP POST content body and returns an ID referring the data.
Read GET ?op=read&id=1 0 Returns the data for ID 10.
Update POST ?op=update&id =1234 Updates the data associated with ID 10.
Delete GET ?op=delete&id =10 Deletes the data associated with ID 10.

A decision tree node can be used to check the correct operation and method combination. The following image displays a decision tree that implements the CRUD configuration in the previous table.

journey-graph-decision-tree-editor.png

In this example, the graph uses the decision tree node defined previously to execute the correct embedded graph based on the value of the op parameter in the Acquia Journey Graph API endpoint of the following graph.

journey-graph-with-decision-branching.png

Web Tracking and recommendation API listener

Acquia recommends that you use the Acquia Lift Profile Manager for tracking webpage activity.

Pixel tracking API listener

Pixel tracking options allow you to use a graph with an API listener in situations where you can load an image but cannot otherwise run code, such as emails or web pages whose source you cannot control. The Acquia Journey API single-pixel image tag can be placed in emails, web pages, and anything else that supports HTML to track HTTP headers and any additional information (such as campaign ID or customer ID) that is passed by the query string.

Email pixel tracking

Pixel tracking passes data from the HTTP request, and an optional URL query string, to your graph. In this example, the previous img tag sends a packet of data into your graph that includes all HTTP headers, and the query parameter name with the value User2:

<img src="https://api.journey.acquia.com/api/v1/listener/[LISTENER_ID]/epixel.gif?name=User2" />

Website pixel tracking

Acquia recommends you use the Acquia Lift Profile Manager for tracking activity on websites.