API v3 Overview

The Foundation Platform version 3 API has made it easier than ever to connect from any external source. A simplified, more straightforward approach to API call creation lessens the learning curve making the Foundation Platform accessible at almost any skill level.

The Basics

Since every programming language is different, having unique requirements and style, each implementation of submitting an API request differs slightly.  For that reason, this overview will cover topics that are shared across all programming languages for implementing a Foundation Platform API v3 request.

The v3 API Request

A v3 API request URL can be broken down into five distinct sections.  In most instances this is true for any API request.  An exception to the norm would be an API request that omits the Action.  Such a request can be used to list all Actions available on a specified Endpoint that are accessible by the given Authentication.  This will be covered in more detail in subsequent articles.

Breakdown of a v3 API Request

  • 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 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/ ].
  • 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 limit what can be done with the API request to Actions that are specifically designed to manipulate 'User' data objects.
  • Endpoint ID/GUID: The Endpoint ID or GUID is the representation of a specific unique data object within the aforementioned Endpoint.  The Endpoint ID/GUID is not required for all API requests. For example, an API request that performs a Search Action will omit the Endpoint ID/GUID.  This can be represented by two different, yet equally effective, values:
    • Endpoint ID: The Endpoint ID is the value which identifies a unique data object within the Foundation Platform internally.  This is always an unsigned integer value.  The above example uses the Endpoint ID.
    • Endpoint GUID: Like the ID, the Endpoint GUID is also a unique identifier that represents a specific data object within the Foundation Platform.  This GUID consists of a unique string of characters and is sometimes also referred to as a 'Key'.  The GUID can be found within the Foundation Platform by opening the 'Edit' modal for the desired object.
  • Authentication: 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 an API Key.  An API Key is a unique string of characters that is created to give access to something in the tool.  To create an API key, open your User Menu on the top right of the screen and select Account Settings. Inside the Account Settings, click on the Generate Token to generate the API Key.
  • Action: The Action tells the system what to do with the specified Endpoint. These are generally broken down into four categories:
    • Getters: Getter actions are used to get data out of the system.  Each Endpoint has a unique set of Getters.  When using a Getter, the correct format is: [ action=<nameOfGetter> ] where [ <nameOfGetter> ] is replaced by the name of the desired Getter .
    • Setters: Setter actions are used to get data into the system, setting or changing properties of a data object.  Each Endpoint has a unique set of Setters.  When using a Setter, the correct format is: [ action=<nameOfSetter>&arg=<valueToSet> ] where [ <nameOfSetter> ] is replaced by the name of the desired Setter and [ <valueToSet> ] is the value to be set.
    • Actions: Actions are used for processes, features or commands of a data object that do not meet the characteristics of a Getter or Setter. One example of an Action is adding fields to a Table.  Each Action is different and has different requirements to be used. For example, some do not require any arguments and are formatted the same as a Getter. Others do require that arguments are included and are formatted like a Setter.  
    • Searches: Searches are used to obtain data from an Endpoint that meets a specific set of parameters. Searches can have an infinite number of search terms and are formatted as an array. For example: [ action=search&args=[{"fname":"Bob","lname":"Selfridge"}] ] would only return records where [ "fname" ] (first name) is [ "Bob" ] AND [ "lname" ] (last name) is [ "Selfridge" ].  Any number of search terms can be used as long as they fit the key:value structure and are separated by commas. Note: When adding the values to the API search request, remember that strings must be inside quotes and numbers must not.

Multiple Actions On a Single API Request

It is possible to make an API request that contains multiple actions. To accomplish this, separate each action with an ampersand ('&'). For example, let's say that you need to change the first name, middle name and last name of a user that has an ID of 15. The request would look like this:

[ https://my.tmmlog.in/api/3/User/15?apikey=45a3d34982e&action0=setFName&arg0=Bob&action1=setMName&arg1=D&action2=setLName&arg2=Smith ]

This request would set the First Name equal to [ "Bob" ], the Middle Name equal to [ "D" ] and the Last Name equal to [ "Smith" ] on the User that has an ID of [ 15 ]. Note: When using multiple Actions in a single API request, the 'action' and 'arg'  MUST be incremented. The first 'action' and 'arg' may be appended by a '0', '1' or nothing.  Each additional action grouping MUST increment by a factor of 1.