Hello World

A simple example to illustrate the basic usage of our RESTful API

Setting Up a TrackVia Application

First of all we will need a TrackVia application to use with our example API applications. Because this is a very basic example of using the API I started with the "Custom Online Database From Scratch" template and then added a table called "Messages" that only has a field called "message" of type short answer. Below is a screen shot of my table.

TrackVia table setup

Authenticating

Now that the application is setup we need to authenticate with TrackVia and get an access token. The access token, along with the user key, are used to verify that you are authorized to use the API and determine which resources you have access to.

First go to our documenation page at https://developer.trackvia.com/livedocs. Click on "OAUTH" and then "/oauth/token." This is the end point that will give you the access token. Fill in your username and password, as seen below.

Provide your credentials to authenticate.

When you click "Try it out!" you should see a JSON object in the Response Body. Your response will be similar to the what's in the image below:

Access token reponse object

The value at the access_token value is your access token to provide to TrackVia to authenticate yourself.

Note, the access_token will expire in the number of seconds in the expires_in value. For programmatic applications the refresh token is used to get a new access token, but for our purposes here, we will just re-authenticate.

Finding the View ID

Everything in the API is based around the idea of a view. This is opposed to thinking of the data at the table level. The reason we do this is that views can filter out certain records and hide certain fields. This provides a level of permissions to the data exposed. Also, when you authenticated, the API will only show things that the user your authenticated as has permission to see. So if your user is limited, it may not see all the views, records, and fields in your TrackVia application. For more on how views work see our knoweldge base

The API uses the unique numeric IDs of resources in TrackVia, instead of their human readable names and labels. These IDs are not exposed in the TrackVia web interface, so to find out these IDs you will use the API.

To get a list of views that your user has access to in the TrackVia application we use the /openapi/view end point. This end point needs both your access token and user key, optionally, you can specify the name parameter to filter for a view with the given name. Below is an example of what the fields should look like before trying this end point.

Parameters for getting a list of views

After running this end point I get the below reponse:

Parameters for getting a list of views

Here you can see that the default view for my Messages table has an ID of 5. The default view is the view created by default when you create a table. This view has permission to see every field in the table.

Creating a Record

Now go to the /openapi/views/{viewId}/records end point. This end points allows us to post a JSON object of the record(s) we want to create. For this example we will only create one record. You can create more than one record using this end point.

Our JSON should look like this:


{
    "data":[
        {
            "message":"Hello world"
        }
    ]
}

We have an object with an element called data which is an array that contains one object per each record to create. The object for a record uses a key/value scheme were the key is the name of the field and the value is the value you want set for that field. This is what my parameters look like in the interactive documenation to create a "Hello world" record.

Parameters for creating a record

After running the end point the response should look something like this:

Response for creating a record

Here you see that the ID of our newly created record is 2. We will need this if we want to modify this record in any way. Also note that the response included all the meta data about the view we just inserted the record into. This will help guide you when reading and writing to a view to make sure the data is handled and formatted correctly.

If we look at TrackVia's web interface we can see our newly created record:

Record created successfully

Updating our Record

Now that we have added our "Hello world" record we realize we have left off the period. To maintain gramatical correctness we need to update our record. We will do this using the /openapi/views/{viewId}/records/{recordId} end point. Below is what the parameters should look like in the interactive documentation. Remember that the record we created had an ID of 2.

Record update parameters

Not the period at the end of the "Hello world." string.

Now when we run this end point we will get the following response:

Record update response

Now we have proper punctuation in our message. If we look at the TrackVia web interface we see that the record has also been updated there:

The properly punctuated message in the web UI

Deleting Our Record

Because we do not want to wear out our welcome we decide to remove our hello. To do this we will use the /openapi/views/{viewId}/records/{recordId} end point, but this time we will use the DELETE method instead of the PUT method we used last time. The parameters for this end point will look something like this:

The parameters for calling the record delete end point

After running that end point we get this response:

The response after calling the record delete end point

This time there's no response body because there is nothing to show, we deleted it. Also note the response is a 204 because the response is intentionally left empty.

If we check the TrackVia web interface we see that the record is gone:

The record has been deleted from the web interface also

That concludes our Hello world tutorial. We hope this gives you a basic understanding of the calls needed to create, update, and delete a record using TrackVia's RESTful API.