GpsGate REST API for getting Events

GpsGate now offers a REST API for getting Events in a fast and efficient way.


Setup and Configuration

GpsGate REST API is a core functionality which is distributed with the Updates.v5 plugin. Installing the plugin updates your application to the latest version of GpsGate REST API. To control access to API resources, “_APIRead” and “_APIReadWrite” privileges are used. “_APIRead” is for granting read-only access and “_APIReadWrite” is for granting read/write access. Most services also offer resource-based privileges which can be used for filtering access to that specific resource. By default, applications/users have no access to API resources. To activate 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 RESTful API
  3. Under API enable _APIRead and _APIReadWrite
  4. Click on Save

After enabling the privileges for an application, follow these steps to allow API 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. Press Save

In order to use GpsGate API, you need an HTTP client. There are many applications available on the Internet that can be used for this purpose. You can also develop your own HTTP client using your preferred programming language. Another alternative is to use our web-based HTTP client for manual testing that is distributed with Updates.v5 plugin. You can reach reach it here: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname). In this tutorial we use yet another client called Postman to show HTTP headers and other details.

Login

The first step to use GpsGate REST API is to login. To login into GpsGate REST API you need to send your username and password to the Token resource. The response of your request will contain an API Token which you can use to authenticate yourself in the following requests. For an example of a login request and how to use the response please read Token section.

Resources and Actions

All available resources are documented in a page hosted by your GpsGate Server installation:
http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname).

GpsGate REST API uses a JSON format for input/output, therefore an “HTTP Content-Type” header with value “Application/JSON” should be sent with all requests. Moreover, an HTTP Authorization header with an API Token as value should be sent along with requests to the resources that require authentication. Here is an example of an HTTP request that is created by Postman. In the next section we explain how to acquire your API token.

Tokens (/applications/{applicationid}/tokens):
As mentioned before, the Token resource is for authentication purposes. This resource is used to login and get an API token back. The token should be sent in all communications with other resources. To get the API token for a user, an HTTP POST request should be sent to the Token resource. In the post body, username and password are specified in JSON format, and the response body contains a token key with an actual API Token as value. The token should be used in an HTTP Authorization header while communicating with other resources. Depending on the client that is used, there are different ways to send HTTP headers.

The following picture shows how to use Postman to send a login request to the Token resource and how the response looks like.

For more information about how to send the token in an authorization header using our test client please read Testing section.

Please note that the full URI of the token resource is “http://{hostname}:{port}/comGpsGate/api/v.1/applications/{applicationid}/tokens” where your GpsGate Server is installed on “{hostname}” and it listens to port number “{port}” (the default port is 80) and “{applicationid}” is Id of the application you are trying to login to. An example of the URI is http://localhost:80/comGpsGate/api/v.1/applications/4/tokens where GpsGate Server is installed on the local computer and listens to the default port and the application we try to login to is application number 4.

Users (/applications/{applicationid}/users):
In the current version of the API, only the HTTP GET request is supported. The HTTP GET request on this resource returns a list of users in the application.

Event Rules (/applications/{applicationid}/eventrules):
HTTP GET can be used to get a list of event rules in an application.

Events (/applications/{applicationid}/events):
HTTP GET can be used to get a list of events for a combination of a specific application, event rule, user, and date. The OpenEvents parameter can be passed to specify if only open events should be returned.

Testing

In order to test the API you can develop your own client or use one of the many third-party tools available on the Internet to generate the client code for your preferred programming language from our standard documentation. GpsGate API documentation is based on the OpenAPI Specification. You can download GpsGate RESTful API specification here: http://host_name/comGpsGate/api/v.1/swagger.json (replace host_name with your actual server IP address or hostname). For quickly accessing the API and manual testing you can use our web-based client available in the documentation page. You can reach the page using this link: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname). The client has been generated using Swagger tools.

Here we provide an example of how to generate an API token for a user and use it for getting a list of tags using our web-based client. First, you visit the documentation page hosted by your GpsGate Server installation. Then a request should be sent to the Token resource as shown in the following picture.

The response from the server contains the API Token (in this case “9Zg4HihvlYr6Y5Py0vdH91O8O6my80Ll30RPUf3S9kpz%2brvLrwtiEPN8eQT%2f5vGe”)

For ease of use, there is an Authorize button on top of the page which can be used to set the API token. After pasting the API token and pressing the Authorize button, the token will be sent in an Authorization header for all the other requests. This functionality can be used to bypass adding an Authorization header for each request during manual testing. The following pictures show how to set the API token.

Please note that the lock icon is locked and the Token will be sent along with all requests. As an example, we use Tags resource, as shown in the following picture to fetch the list of tags.

Performance and Pagination

To improve the performance and have better scalability, there is a limit of 1000 records in the response of any HTTP GET request. This number can be decreased by sending PageSize parameters in the query string of your request, however it cannot exceed 1000. If there are more records than the number specified in the PageSize parameter (or 1000 by default), a link to the next page is sent back along with the response in x-pagination header. Here is an example of x-pagination header for a request where the specified PageSize was 100.

 

Support

Please contact us if you need any help or want to make a suggestion: .(JavaScript must be enabled to view this email address) or you can post your questions in our forum under GpsGate RESTful API topic.


  Discuss this blog post on the forum please



Download free GpsGate Server

Install it on your own server. The installation is free for 5 users.

Download Now