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:
- The client initiates the
requests via the APIs URI;
- Upon receiving the request,
the API initiates a call to the server;
- Subsequently, the server
responds by sending back the requested information to the API;
- 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:
- Send
client secret + Id to authorization server;
- Server
sends back bearer token;
- You
can now add the bearer token to the request header when calling an endpoint;
- 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:
- Click on the link highlighted in the
image below. This link will direct you to the JSON data containing all the
endpoints.
- Copy the JSON data and save it
into a .txt file;
- Go to Postman, click on
“Import”;
- Choose the file to import;
- 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:
- Go to EyeQuestion
API
- Go to "Variables
- Add the variable
{baseUrl} and provide both the initial and current values
- Click on “Save”
to apply the changes
After setting up the baseUrl,
- Go to the end point “Retrieve bearer token”
- Enter the client_id and client_secret
- Click “Send"
- Response will contain the token
- Copy the token and go to EyeQuestion API (as shown
in the second image below)
- Go to “Variables”
- Add a new variable named “apiKey” with value
Bearer {token}
- Click “Save” to apply the changes



To make the first API call, let's retrieve the projects:
- Go to “Get projects” endpoint
- If you want to retrieve all projects without any
filters, uncheck the "Query Params" option
- Click
“Send"
- The response will return a list of all projects
For any questions don't hesitate to reach out to our support team!