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.


API Documentation (Swagger) 

The EyeQuestion API is documented in Swagger. Use it to see which endpoints are available, what parameters they take and what they return. Under any endpoint, click Schema to see a description of each field. 

Access to the EyeQuestion API is not enabled by default and must be requested through our support team. To get started, please send Support (support@eyequestion.nl) a short description of how you would like to use the API. Our team will review your request and confirm the access options available for your subscription. Depending on your license tier, API access may be included or offered as a paid add-on.

Once access is confirmed, we will provide your OAuth 2 credentials (client ID and client secret) and access to our Swagger documentation page, so you can begin integrating EyeQuestion with your applications.





To understand the meaning of each field in the JSON, click on "Schema". This will display a detailed description of what each field 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 highlighted 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

Go to Postman, and import the .txt file using the "Import API and collections" option as shown below.






Once the import is completed,  all the endpoints available in the Swagger documentation will be visible 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,

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







To make the first API call, let's 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


For any questions don't hesitate to reach out to our support team!