Documentation and SupportSystem Manual API v3Searching for a Specific Endpoint ID

Searching for a Specific Endpoint ID

This article is a continuation of the article: API v3 Search Request Overview.  This article outlines the process in which one may use the API v3 Search Request to receive the ID of a desired Endpoint by configuring the filter array.  This document also covers how to determine what attributes are available to filter against on a given Endpoint.

Determine which Endpoint that should be searched against.

Each object in the TMMData Foundation Platform has a corresponding Endpoint that can be searched against using a filter array.  The first step in identifying a specific ID is to determine which Endpoint must be used in the API Search Request.  More information on Endpoints as well as a listing of all current Endpoints can be found in the article: API v3 Endpoint Overview.  Once the required Endpoint has been identified, the next step is to request the list of attributes that may be searched against.  (For this article, the 'User' Endpoint will be used.)

Request list of attributes available to selected Endpoint.

Each Endpoint has a specific list of attributes that contain values, some shared and some unique, that may be searched against using the API v3 Search Request.  To receive the list of attributes for an Endpoint, a simple API v3 Request can be made.  An API v3 Request for Endpoint attributes only requires three basic pieces of information:

  • Base URL: The Base URL will be the same regardless of the specific API request being made.  To determine what your Base URL should be comprised of, simply copy the URL that you use to log into the TMMData Foundation Platform.  For example, if you log into [ https://random.tmmlog.in ] to access the Foundation Platform, then the Base URL for all of your API requests would be: [ https://random.tmmlog.in/api/3/ ]. (In this example, the Base URL is 'my.tmmlog.in')
  • Endpoint: The Endpoint represents the object, or collection of objects, that the request is intended to interact with.  In the above example, the Endpoint in the 'Example API Request' is 'User'.  This will cause the system to only return attributes relating to 'User' data objects.
  • Userkey: This part of the API Request informs the system that the request should be processed with the same permissions as the specified user.  This will always be represented by a user GUID.  A user GUID is a unique string of characters that is associated with a specific user of the TMMData Foundation Platform.  To find your GUID, first log into the system. Next, click the 'Peg Man' icon on the top-left.  Finally, from this menu click 'My Account Settings'. Scroll down, your GUID is located underneath the 'Key' heading. (In this example, a dummy Userkey is used for security purposes)

Executing API v3 Request and the response received.

Now that the API Request contains all required information, it can be executed.  Every successful v3 API Request will return data in the form of a JSON object.  A JSON object is a standard format for representing structured data which is commonly used for representing and transmitting data on web sites.  Since the request that was executed did not include an Endpoint ID, the JSON response will contain all NULL data.  The data is not what is important here, the name of the attribute before the data is what we are looking for.  These are the Endpoint attributes.  Here is the result received from the example API Request:

{  
   "data":{  
      "type":"User",
      "attributes":{  
         "user_id":null,
         "user_guid":null,
         "fname":null,
         "mname":null,
         "lname":null,
         "email":null,
         "phone":null,
         "user_type_id":null,
         "cust_id":null,
         "adobe_key":null,
         "login":null,
         "theme":null,
         "last_active":null,
         "is_active":null,
         "exceptions":null,
         "notes":null,
         "two_factor":null,
         "auth_token":null,
         "expires":null,
         "password_history":null,
         "access_type":null,
         "notification_preference":"noti",
         "primary_id":"user_id",
         "primary_guid":"user_guid"
      },
      "meta":{  }
   },
   "meta":{  },
   "self":"https:\/\/my.tmmlog.in\/api\/3\/User?userkey=453456345645"

The attributes that can be used to search against can be found within the JSON response object -> "data" -> "attributes".  In this example, using the User Endpoint, the attributes are as follows: user_id, user_guid, fname, mname, lname, email, phone, user_type_id, cust_id, adobe_key, login, last_active, is_active, exceptions, notes, two_factor, auth_token, expires, password_history, access_type, notification_preference, primary_id, primary_guid.  Any or all of these attributes may be used in a Filter Array to zero in on a specific Endpoint ID.

 

The Search Action and creating a Filter Array

We have now acquired all of the information needed to create our Search Action, including the Filter Array containing all of the attributes and values representing the desired Endpoint ID.  This Action, [ &action=search ], configures the system to accept a Filter Array that will determine the search parameters.  Note that the Action is prepended by an ampersand (&), all variables following the first are prepended with an ampersand.

Creating the Filter Array

At this point, the Filter Array can be created.  Depending on the information available to us, relating to the User we are searching for, we will use different attributes to build our Filter Array.  We will assume that we know the following information:

  • The User's first name: Barry
  • The User's customer ID: 52342321
  • The User is active

There are multiple conditionals available to make searching easier.  The following is the list of conditionals that may be used for making comparisons:

Valid options:

  • eq (equal to)
  • ne (not equal to)
  • bw (begins with)
  • ew (ends with)
  • cn (contains)
  • bn (does not begin with)
  • en (does not end with)
  • nc (does not contain)
  • in (in [comma seperated list])
  • ni (not in [comma seperated list])
  • nu (NULL)
  • nn (Not NULL)
  • lt (less than)
  • le (less than or equal to)
  • gt (greater than)
  • ge (greater than or equal to)

Knowing this information and the list of attributes available for the User Endpoint, we determine that we need the attributes fname, cust_id, and is_active.  The Filter Array would be as follows:

[ &args=[{"fname":["eq","Barry"],"cust_id":["eq","52342321"],"is_active":["eq","1"]}] ]

The full API v3 Search Request would be as follows:

[ https://my.tmmlog.in/api/3/User?userkey=453456345645&action=search&args=[{"fname":["eq","Barry"],"cust_id":["eq","52342321"],"is_active":["eq","1"]}] ]

When we execute this request we receive a single result:

{  
   "data":{  
      "type":"User",
      "attributes":{  
         "user_id":17,
         "user_guid":"75647362",
         "fname":"Barry",
         "mname":"Earl",
         "lname":"Smith",
         "email":"barry.smith@tmmdata.com",
         "phone":"111-555-1312",
         "user_type_id":20,
         "cust_id":"52342321",
         "adobe_key":null,
         "login":null,
         "theme":"3c",
         "last_active":"2017.10.31 09:53:01",
         "is_active":1,
         "exceptions":null,
         "notes":null,
         "two_factor":null,
         "auth_token":null,
         "expires":null,
         "password_history":null,
         "access_type":50,
         "notification_preference":"noti",
         "primary_id":"user_id",
         "primary_guid":"user_guid"
      },
      "meta":{  }
   },
   "meta":{  },
   "self":"https:\/\/my.tmmlog.in\/api\/3\/User?userkey=453456345645"

We've found it!  The Endpoint ID that we were looking for is 17.  Now any API v3 Request we make that would affect this User would contain this ID.