Minitab Connect®  Support

Search requests

Learn more about Minitab Connect
The search action allows the querying of any endpoint to receive desired data that has been filtered. The user may choose to manipulate the response by adding one or more filters that adjust the range of returned data. There is no limit on the number of filters that can be used in an API request.

In This Topic

Details of a version 3 API search request

Here is a example search request.

Endpoint
Represents the object, or collection of objects, of the request.

In the above example, the endpoint is source, which limits what can be done with the API request to actions that are specifically designed to manipulate user data objects.

Action
Specifies what actions to take for the specified endpoint.

In the above example, the action is Search. Search is used to obtain data from an endpoint that meets a specific set of filters.

Filter Array
Holds the list of required parameters that must be met before a data object will be returned by the API request. A search can have an infinite number of filters that are formatted as an array. An array is defined as an arrangement of interrelated objects or items for accomplishing a particular task.
In the version 3 API, an array is structured as follows: {KeyValue}.
  • Key: The search attribute which must be enclosed in double quotes (").
  • Value: The string or number to be matched against the key. For example: action=search&args=[{"full_name":"Steve Joe"}] would only return records where "full_name" (Key) is "Steve Joe" (Value). Any number of filters can be used as long as they fit the Key:Value structure and are separated by commas.
Note

When you add filter values to the API search request, text strings must be inside quotes.

The Minitab Connect API endpoint search action is limited to simple queries. Compound search requests must be against different keys. For example: {"A":"Bob"},{"B":"Test"}. Querying a key twice in the same search request results in a response that contains all results that match only the second condition. Complex queries against a single key are possible via the source interface endpoint using js_filter.

API response data

Every successful version 3 API request returns data in the form of a JSON object. In this example, we will focus on a simple API response.

The version 3 API request

The API request that will be used is the 'Example API Request' above.1 A breakdown of the example follows:

https://connect.minitab.com/api/3/User?apikey=45354645654474127781&action=search&args=[{"full_name":"Steve Joe"}]

  • This request connects to the system at https://connect.minitab.com/ and specifies that this is a version 3 API request with /api/3.
  • The Endpoint /User is the core of the API requests and everything that follows will point to it. In this example, access to the user endpoint is requested.
  • Before granting access, the system must determine if the request comes from an authorized source. The request provides credentials for the server to authenticate ?apikey=4535464564474127781 2
  • Because this is the first variable in the request URL, it must be prepended with a question mark (?).
  • After passing authentication, the system moves to the action. &action=search This action configures the system to accept a filter array that will determine the search parameters.
    Note

    This configuration variable is separated from the API key by an ampersand (&). All variables except for the first variable are prepended with an ampersand.

  • At this point, the filter array is read. &args=[{"full_name":"Steve Joe"}] The filter array instructs the system to search the Userdata objects and return all that have an attribute of full_name that is equal to "Steve Joe".
  • The system returns the JSON object that contains all the results.

The response object

The response received from an API request is a JSON object that contains all User data objects with attribute "fname" with a value of "Steve". All response objects have the same basic structure, and they are returned as a JSON-formatted string.

The JSON formatted string

{"data":[{"type":"User","id":"999","attributes":{"user_id":"999","user_guid":"558877tu8822","full_name:"Steve
	 Joe","email":"Steve_Smith@minitab.com","phone":"","user_type_id":"66","cust_id":"1","adobe_key":null,"login":null,"theme":"","last_active":null,"is_active":"1","exceptions":[],"notes":"","two_factor":"0","auth_token":null,"expires":null,"password_history":null,"access_type":"40","notification_preference":"noti","primary_id":"user_id","primary_guid":"user_guid"},"meta":{"valid":true,"getters":{"EXCEPTIONSON":"getExceptionsOn","FULLUSERLIST":"getFullUserList","CUSTOMERUSERLIST":"getCustomerUserList","NOTIFICATIONS":"getNotifications","DBSTATUS":"getDBStatus","DBTABLES":"getDBTables","DBVIEWS":"getDBViews","JOBS":"getJobs","UIREFRESH":"getUIRefresh","USERGUID":"getUserGUID","USERID":"getUserID","NAME":"getName","FULLNAME":"getFullName","FNAME":"getFName","MNAME":"getMName","LNAME":"getLName","EMAIL":"getEmail","PHONE":"getPhone","ADOBEKEY":"getAdobeKey","LOGIN":"getLogin","CUSTID":"getCustId","USERTYPEID":"getUserTypeID","THEME":"getTheme","LASTACTIVE":"getLastActive","ISACTIVE":"getIsActive","EXCEPTIONS":"getExceptions","NOTES":"getNotes","TWOFACTOR":"getTwoFactor","AUTHTOKEN":"getAuthToken","EXPIRES":"getExpires","PASSWORDHISTORY":"getPasswordHistory","CUSTOMERSTATS":"getCustomerStats","RELATIVES":"getRelatives","ACCESSTYPE":"getAccessType","NOTIFICATIONPREFERENCE":"getNotificationPreference","ACTIVEUSERS":"getActiveUsers","CONTYPE":"getConType","ID":"getID","PRIMARYID":"getPrimaryID","GUID":"getGUID","PRIMARYGUID":"getPrimaryGUID","PROPERTIES":"getProperties"},"setters":{"CDBO":"setCDBO","USERGUID":"setUserGUID","FNAME":"setFName","MNAME":"setMName","LNAME":"setLName","EMAIL":"setEmail","PHONE":"setPhone","ADOBEKEY":"setAdobeKey","LOGIN":"setLogin","CUSTID":"setCustID","USERTYPEID":"setUserTypeID","THEME":"setTheme","LASTACTIVE":"setLastActive","ISACTIVE":"setIsActive","PASSWORD":"setPassword","NOTES":"setNotes","TWOFACTOR":"setTwofactor","AUTHTOKEN":"setAuthToken","EXPIRES":"setExpires","PASSWORDHISTORY":"setPasswordHistory","ACCESSTYPE":"setAccessType","NOTIFICATIONPREFERENCE":"setNotificationPreference","ID":"setID","DBO":"setDBO"},"actions":{"load":{"parameters":[{"name":"args"}]},"loadExceptions":{"parameters":[]},"addException":{"parameters":[{"name":"args"}]},"updateException":{"parameters":[{"name":"args"}]},"removeException":{"parameters":[{"name":"args"}]},"clearExceptions":{"parameters":[]},"search":{"parameters":[{"name":"args"}]},"remove":{"parameters":[]},"checkPassword":{"parameters":[{"name":"password"}]},"checkPasswordHistory":{"parameters":[{"name":"password"}]},"runDBSQL":{"parameters":[{"name":"args"}]},"removeUIRefresh":{"parameters":[{"name":"args"}]},"createUIRefresh":{"parameters":[{"name":"args"}]},"systemLog":{"parameters":[{"name":"args"}]},"checkLogIn":{"parameters":[{"name":"args"}]},"logIn":{"parameters":[{"name":"args"}]},"removeUser":{"parameters":[]},"whois":{"parameters":[{"name":"auth_token"}]},"auth":{"parameters":[{"name":"args"}]},"commit":{"parameters":[]},"purge":{"parameters":[{"name":"args"}]},"checkRequirements":{"parameters":[{"name":"password"}]},"checkHistory":{"parameters":[{"name":"password"},{"name":"limt"}]},"grantAccess":{"parameters":[{"name":"args"}]},"removeAccess":{"parameters":[{"name":"args"}]},"notify":{"parameters":[{"name":"args"}]},"sharableList":{"parameters":[]},"slackAccounts":{"parameters":[]},"sendSupportRequest":{"parameters":[{"name":"args"}]},"downloadActiveUsers":{"parameters":[{"name":"args"}]},"message":{"parameters":[]},"beginTransaction":{"parameters":[]},"commitTransaction":{"parameters":[]},"rollbackTransaction":{"parameters":[]},"restrictCustomer":{"parameters":[]},"permissionRequired":{"parameters":[{"name":"args"}]}}}}],"meta":{"data_type":"array"},"self":"https:\/\/connect.minitab.com\/api\/3\/User?apikey=5555888817ab43&action=search&args=[{%22full_name%22:%22Steve
	 Joe%22}]"}

Searching for a specific endpoint GUID

This topic outlines the process to use the API version 3 search request to receive the GUID of a desired endpoint by configuring the filter array. It 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 Minitab Connect 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 Minitab Connect API. 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.)

Executing API version 3 request and the response received

When your API request contains all the required information, you can execute the request. Every successful version 3 API Request returns data in the form of a JSON object. Because the request did not include an endpoint ID, the JSON response will contain all NULL data. However, the data is not what is important; in this example, the name of the attribute before the data is what we are looking for. These are the endpoint attributes. Here is the result 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 the information that is needed to create our search action, including the filter array that contains all the attributes and values that represent 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 (&). Remember that all variables except for the first variable are prepended with an ampersand.

At this point, you can create the filter array. Depending on the information available to us, we will use different attributes to build our filter array. Let's assume that we know the following information:

  • The User's name: Barry Joe
  • The User is active
Multiple conditionals are available to make searching easier. The following is the list of conditionals that may be used to make comparisons:
  • 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-separated list])
  • ni (not in [comma-separated list])
  • nu (NULL)
  • nn (Not NULL)
  • lt (less than)
  • le (less than or equal to)
  • gt (greater than)
  • ge (greater than or equal to)

With 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 is as follows:

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

The full API version 3 search request is as follows:

https://connect.minitab.com/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"

The endpoint ID is 17. Any future API version 3 Request that would affect this User will contain this ID.

1 The example API request contains an invalid API key for demonstration purposes and will result in an error if used as is. This is for security purposes. A valid API key was substituted to generate a valid API response.
2 The API key provided is for demonstration purposes only. A valid API key must be provided or the API Request will result in an error.
Copyright © 2024 Minitab, LLC. All rights Reserved.