Developer REST APIs Quick Start


Getting Started

Use GpsGate REST API to query, create, edit and remove different resources, including but not limited to Users, Tags, Tracks, Events, and Event Rules.

In this article we provide a step by step guide on how to use GpsGate REST API.

Setup and prerequisites
Latest version of Updates.v5

In order to use GpsGate REST API, the latest version of Updates.v5 plugin is needed.

Enabling API privileges in applications

_APIRead” and “_APIReadWrite” privileges are used to control access to API resources. “_APIRead” is for granting read-only access and “_APIReadWrite” is for granting read/write access. These two privileges need to be enabled in all the applications in which you want to use GpsGate REST API.

To enable GpsGate REST API privileges for an application, follow these steps:

  1. Login to SiteAdmin
  2. Navigate to Applications and select the application in which you want to grant access to GpsGate REST API
  3. Go to Privileges and Features section
  4. In the privileges tree under API enable _APIRead and _APIReadWrite
  5. Scroll down and click on the Save button

Some services also offer resource-based privileges which can be used for filtering access to that specific resource.

Granting GpsGate REST API privileges to specific roles

After enabling GpsGate REST API privileges in some applications, you need to grant the privileges to your desired Roles. Only users in your selected Roles can use GpsGate REST API. Follow these steps to allow access to the Roles you choose:

  1. Login to the application
  2. Select Roles from the Admin menu
  3. Create a new role for API users or edit an existing role
  4. Under the Users section, select the users you want to add to this role
  5. Under the Privileges section, enable “_APIRead” privilege for read-only access and “_APIReadWrite” privilege for full access
  6. Click on Save
First Query (Getting Users)

As the first query, we demonstrate how to get list of users through GpsGate REST API.

Firs, visit our web-based HTTP client for manual testing. You can reach it here: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname).

The first step for communicating with GpsGate REST API is getting an API token. A token is similar to a username/password and is used for authentication. Each user has its own API Key and it will be always the same key unless the user changes her/his password. To get your API key, follow these steps:

1. Visit this page: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname)
2. Scroll down and find the Tokens section:

3. Open Token resource and press “Try it out”

4. Fill out the form and click on Execute.
“applicationid” is the id of the application your user belongs to. Write your username and password in the credentials field. For example, the following picture shows a filled out form for a user that belongs to application 4 and with the username: “test” and the password: “mypass”.

5. After clicking on Execute, you will receive a JSON response which contains your GpsGate REST API key. We will use this key for authentication in the rest of this article. In our example, the GpsGate REST API Key for user “test” is “9Zg4HihvlYr6Y5Py0vdH91O8O6my80Ll30RPUf3S9kpz%2brvLrwtiEPN8eQT%2f5vGe”.

Now that we have our REST API Key, we can use it to query from other resources.

The acquired key should be sent in an HTTP header with every request to GpsGate REST API. To simplify this process in our web-based client, we have provided a place where you can store the key and the page will send it with requests. Follow these steps to set your key in the page:

1. Click on the Authorize button on the top of the page

2. Paste your GpsGate REST API key in the form and click on the Authorize button

3. Check that the lock icon next to resources is locked

The final step is to use Users resource to get list of users in an application. Find Users category in the page and open “/applications/{applicationid:int}/users” section.

Fill out the form and click on Execute. In this resource, the only mandatory field is application id. In this example, we want to get users in application 4.

After executing the query, you get a list of users in the specified application in JSON format.

For another example, please refer to this article. We also demonstrate how to use Postman as an alternative application for interacting with GpsGate REST API.

Support

Please contact us if you need any help or want to make a suggestion: .(JavaScript must be enabled to view this email address)