EyeQuestion API

EyeQuestion API

What is API?

API stands for application programming interface, which is a set of definitions and protocols for building and integrating application software. These interfaces establish a secure and standardized means for different applications to collaborate, and exchange of information or functionality without requiring user intervention.

How does API work?

The working of an API can be explained with a few simple steps:

  1. The client initiates the requests via the APIs URI;
  2. Upon receiving the request, the API initiates a call to the server;
  3. Subsequently, the server responds by sending back the requested information to the API;
  4. API sends back the response to client;

To clarify the concept with a diagram, consider a real-life analogy: think of an API as similar  to a waiter in a restaurant. When you place an order request, the API acts like the waiter, conveying your request to the chef, retrieving the requested food items, and returning to you with the fulfilled order. This real-life scenario serves as a practical illustration of how an API facilitates seamless communication and data exchange between different components.


Understanding Machine-to-Machine Authentication with OAuth 2 in EyeQuestion API

The EyeQuestion API requires machine-to-machine authentication, using the OAuth 2 protocol. This means that to access the API endpoints, the requesting machine must obtain a token to identify itself.

To illustrate this see the diagram below:

 

In the flowchart above you see how the authentication flow works with the following steps:

  1. Send client secret + Id to authorization server;
  2. Server sends back bearer token;
  3. You can now add the bearer token to the request header when calling an endpoint;
  4.  API returns response.

This authentication flow ensures secure communication between machines, allowing you to seamlessly integrate and utilize EyeQuestion's API functionalities in your application.

A common resource with a vast amount of information regarding OAUTH authentication can be found here.

HTTP Response Codes

When interacting with the EyeQuestion API, all endpoints will return default HTTP response codes like 200, 201, 204, 400, 403, 405, 422 and 500.

Below you’ll find what each of them means.

Field

 

200

Ok – The request was executed successfully

201

Created – The request was executed successfully

204

No Content - The request was successful, but there is no content to send in the response.

400

Bad request – A common cause is a problem in the data sent to the API. Such as  a wrong URL parameter or incorrect JSON.

403

Forbidden – This indicates a problem with the authorization.

405

Method not allowed - Most common causes are the incorrect specification of the request being a GET, POST or PUT

422

Unprocessable Entity – There is a problem in the data sent to the server.

500

Internal server error – This usually refers to an unexpected error.

How to use API in EyeQuestion using Swagger 

There are many ways to connect to the EyeQuestion API (using any application that supports OAuth2 protocol) like Swagger and Postman. For efficient interaction we have a Swagger documentation page. To access this documentation, please contact our support team at support@eyequestion.nl.

This tutorial will help you get started with using the EyeQuestion API. Follow the steps below to seamlessly integrate EyeQuestion's functionalities into your application.

Step 1: Obtain OAuth 2 Credentials

First, you need to get your OAuth 2 credentials, for using API from EyeQuestion. This includes the client ID and client secret. To do this, please contact us at support@eyequestion.nl.

Step 2: Retrieve Bearer Token 
Next, you need to retrieve a bearer token:
  1. Go to the Authentication Controller;
  2. Find the call to "Retrieve bearer token" and click on "Try it out";
  3. Enter the client ID and client secret obtained in Step 1;
  4. Press "Execute" to retrieve the bearer token.




Step 3: Authorize
  1. Copy the bearer token received in Step 2 from the response body;
  2. Click on "Authorize";
  3. Paste the token in this format: Bearer {token}. (See image below);
  4. Press "Authorize";
  5. Click “Close”.




Step 4: Make Your First API Call

You are now authorized and can start making API calls.
For example, let's retrieve the list of all projects using the "Get projects" API endpoint.
This call retrieves list of projects based on status, field value and change date.
The “changedSince” and “changedBefore” dates don’t just check when the most recent edit to the project has taken place, it also takes into account when the most recent data was collected.

In this API call, all parameters are optional. Here's are the steps to follow:
  1. Go to the Project Controller;
  2. Click on “Get projects”;
  3. Click on "Try it out";
  4. Press "Execute";
  5. All projects matching the criteria will be returned.





To understand the meaning of each key, click on "Model". This will display a detailed description of what each key represents.



How to import endpoints in Postman (or another application)

To enhance usability, these API endpoints can be easily imported into your preferred application. This example demonstrates how to import these endpoints into Postman.

Here are the steps to follow:
  1. Click on the link shown in the image below. This link will direct you to the JSON data containing all the endpoints.
  2. Copy the JSON data and save it into a .txt file;
  3. Go to Postman, click on “Import”;
  4. Choose the file to import;
  5.  All the endpoints will be imported in Postman.





Postman








The EyeQuestion API endpoints are now ready to be used in Postman.
Next,
  1. Go to EyeQuestion API
  2. Go to "Variables
  3. Add the variable {baseUrl} and provide both the initial and current values
  4. Click on “Save” to apply the changes


    After setting up the baseUrl,
  1. Go to the end point “Retrieve bearer token”
  2. Enter the client_id and client_secret
  3. Click “Send"
  4. Response will contain the token
  5. Copy the token and go to EyeQuestion API (as shown in the second image below)
  6. Go to “Variables”
  7. Add a new variable named “apiKey” with value Bearer {token}
  8. Click “Save” to apply the changes





To make the first API call, lets retrieve the projects,
  1. Go to “Get projects” endpoint
  2. If you want to retrieve all projects without any filters, uncheck the "Query Params" option
  3. Click  “Send"
  4. The response will return a list of all projects


    • Related Articles

    • Introduction to EyeQuestion 6

      We could not be more excited to announce the release of our latest software update, version 6, packed with new features designed to enhance user experience, including: Improved Panel Management: Streamline workflows with our enhanced panel management ...

    • EyeQuestion's Site Functionality

      One of the features available in EyeQuestion is the ability to set up sites. This functionality enables researchers to manage and organize surveys by location, department or research project. Users can have access to one or multiple sites, in order ...

    • EyeQuestion Quota Management

      Introduction EyeQuestion Quota Management is a new functionality that enables users to efficiently monitor and control access to their questionnaires. This innovative feature not only streamlines the questionnaire administration process but also ...

    • Available Placeholders in EyeQuestion

      Introduction Placeholders are special codes that can be used to display dynamic information to your panelists. Dynamic information is information other then static text. Placeholders can show information that is attached to your products such as the ...

    • Question Types Available in EyeQuestion

      In EyeQuestion you have two libraries of question types available. Your own custom template library and the default system template library. The default library contains a wide range of question types and are divided into several subfolders. Question ...