Overview for developers
Introduction
Data Connect is an Application Programming Interface that lets you, as a Qmatic customer, access your data generated in Qmatic systems. It allows for direct access from business intelligence tools and system integration. To be compatible with all the different business intelligence tools and provide a good developer experience, Qmatic has chosen to use the OData protocol as the core technology for Data Connect.
Intended audience
This text guides developers who want to integrate with Data Connect and bring data into their system. Since Data Connect uses a standardized protocol, this text will also help developers find resources and other help texts about the OData protocol.
The OData protocol
The OData protocol is a standardized protocol with the ISO and OASIS organizations. It follows the RESTful principles of API design and is therefore very easy to adopt for developers that have worked with REST APIs. The difference between your typical REST implementation and OData is that it standardizes schemas, metadata and interactions. The closest technology would be a database protocol. You connect to a service and get the schema. From that schema, you can do querying and most CRUD operations.
Getting started
The best way to get started is to read the beginner tutorial in the Resources section. Then look around with the service endpoint in your browser, Postman, or similar tools to get a feel for the look and feel of the protocol. You can obtain the service endpoint URL from your Qmatic system administrator. The next step is to choose a library for the language and platform you use. You can interact with the Data Connect without a client library. However, Qmatic recommends using a client library for the best maintainability and compatibility.
Data time ranges
The URLs come in a pair of two URLs. One URL gives you the data from the last 60 days. The long term URL gives you data from a time range between 3 years before the start of the current until the current day.
Short term
If today is 2022-05-01, the short term url ending with ../short-term will give you data from 2022-03-01 until 2022-05-01.
Long term
If the current date is 2022-05-01, the long term URL ending with ../long-term will give you data from 2019-01-01 until 2022-05-01.
Exploring Data Connect
Normally, you would use a library or a BI tool/system to interact with the API, but for exploration purposes you can use the following tools:
Postman
To work with Data Connect using Postman, you first need to install Postman. Postman is a web application that allows you to interact with web APIs. You can can find a tutorial on how to interact with OData services using Postman here.
curl
To use curl to interact with Data Connect, you first need to install curl. curl is a command line tool that allows you to interact with web APIs. You can can follow the instructions in the tutorial mentioned for Postman in the paragraph above.
Encryption
The service is encrypted using Transport Level Security (TLS).
Authentication
The OData specification requires Basic Authentication for the best interoperability, and the Data Connect follows the OData specification and implements that requirement. Please get in touch with an administrator for the Qmatic system deployed for your company to get the credentials.
Performance considerations
Data Connect allows you to read all data at once. It is, however, recommended to only read the changes since the last query. Doing this is especially important for the fact tables that contain large amounts of data. For more slowly changing entities, Qmatic recommends you to implement caching.
Tips and tricks
- The OData protocol supports both XML and JSON. You can control the format by changing the accept HTTP header.
Limitations
Read only
The data in Data Connect is read-only. You can not perform any of the OData operations that modify data. An error will be returned when a request is made that attempts to write or modify data.
Rate limiting
Data Connect has a rate limit, set by the Qmatic system administrator. If you exceed the rate limit, you will get an HTTP 429 error. If you get this error, you need to slow down your fetching process.
Due to the ETL process in aggregating the data, this is not a real-time API. Any system that integrates with this API should fetch data not faster than every 30 minutes. Choose a random starting time for the fetching process. Ex: 13:47 is better than 13:00. This reduces any risk of disturbing your other processes.
Quota
Data Connect has a quota, and the Qmatic system administrator sets that limit. If you exceed the quota, you will get an HTTP 429 error. The quota limits the number of entities you can fetch in a given time period. An entity is for example one Visit, Branch, or Service etc. When you pull data from Data Connect, you pull entities contained in entity sets.
The current quota is 5 000 000 entities per 24 hours. When you get the HTTP 429 error you will get an error message stating how long it will take until your quota is reset.