DocumentationSystem 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 Minitab Connect 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 Minitab Connect Platform.  For example, if you log into [ https://connect.minitab.com ] to access the Minitab Connect Platform, then the Base URL for all of your API requests would be: [ https://connect.minitab.com/api/3/ ].  (In this example, the Base URL is 'connect.minitab.com')
  • 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.
  • APIKey: 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 GUID.  An APIKey is a unique string of characters that is associated with a specific user of the Minitab Connect 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'.  A list of available APIKeys will be listed with the ability to generate new ones.  (In this example, a dummy apikey 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,
         "full_name":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:\/\/connect.minitab.com\/api\/3\/User?apikey=411412489453456345645"

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, full_name, 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 name: Barry Joe
  • 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 full_name, cust_id, and is_active.  The Filter Array would be as follows:

[ &args=[{"full_name":["eq","Barry Joe"],"is_active":["eq","1"]}] ]

The full API v3 Search Request would be as follows:

[ https://my.tmmlog.in/api/3/User?apikey=411412489453456345645&action=search&args=[{"full_name":["eq","Barry Joe"],"is_active":["eq","1"]}] ]

When we execute this request we receive a single result:

{  
   "data":{  
      "type":"User",
      "attributes":{  
         "user_id":17,
         "user_guid":"75647362",
         "full_name":"Barry Joe",
         "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:\/\/connect.minitab.com\/api\/3\/User?apikey=411412489453456345645"

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.