Developers Getting Started with REST


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 and 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 those 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 privileges tree, under API enable _APIRead and _APIReadWrite
  5. Scroll down and click on 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 Admin menu
  3. Create a new role for API users or edit an existing role
  4. Under Users section, select the users you want to add to this role
  5. Under 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.

First 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).

First step for communicating with GpsGate REST API is to get an API token. A token is similar to 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 you 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 Tokens section:

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

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

5. After clicking on Execute you will receive a JSON response which contains you GpsGate REST API key. We will use this key for authentication in the rest of this article. In our example 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 Authorize button on top of the page

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

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

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 up 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 blog post. In this blog post 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)