Technical Documentation
This page outlines the technical specifications for an interface to the DoorVision application. It describes the API needed to pull the visual doors information from your shop-system. There are multiple other options to set-up an API to DoorVision, however the 'LIVE PULL API' is our recommended solution.
Getting the visual doors via an API from your shop-system
In order to visualize the doors from your shop-system DoorVision needs to gather all the information for the doors which should be shown. Additionally all the possible filter- and sorting options need to be available via an API.
The following API endpoints need to be provided by your shop-system. The exact technical implementation details may vary as long as all the needed information is returned. We will implement a custom adapter to your shop-system which will execute all the needed API calls, therefore we are quite flexible when it comes to the exact data structure of the returned data. In the following we are proposing the simplest possible API endpoint design consisting of the following endpoints:
-
Get door by external id
-
Get paginated list of doors (input array of external ids)
-
Get filter and sorting options
-
Get paginated list of doors (input is the selected filter and sorting option from the user)
1.) Get door by external id
This endpoint gets an external id as the input and delivers the following fields as a JSON response:
* The shop link can either be defined individually per visual door or a general url structure can be defined to calculate the shop link with the help of the external id. For example the url structure “https://www.brandname.com/collections/internal-doors/products/<externalId>” would lead to the visual door with the given external id.
Example:
URL: https://www.brandname.com/api/door/<externalId>
Result:
2.) Get paginated list of doors (input array of external ids)
In order to show the DoorVision users a list of doors which they marked as favorite, your shop-system needs to provide an endpoint to get a paginated list of doors for an array of external ids. DoorVision takes care of storing the external ids marked as favorite.
Example:
URL: https://www.brandname.com/api/doors/
Query-Parameters:
-
externalIds: Array<string>
-
page: number
-
pageSize: number
Result:
3.) Get filter and sorting options
This endpoint delivers all the possible filter and sorting options.
The top level for the filter is a list of categories for example “Brand”, “Door style”, “Glazing”, “Finish”.
A category consists of the following properties:
-
id: string
-
name: string
-
description: string (optional)
-
enabled: boolean
-
options: List of
-
id: string
-
name: string (optional)
-
count: string (optional)
-
The count of doors which would be included in this filter category option
The sorting options are represented as a list of:
-
id: string
-
name: string
Example:
URL: https://www.brandname.com/api/filterOptions/
Parameters:
-
doorType: single | double (optional)
-
selectedSortingOptionId: string (optional)
-
selectedCategoryOptions (optional)
-
Array of:
-
categoryId: string
-
selectedOptionIds: Array<string>
-
-
Result:
4.) Get paginated list of doors
This is the main request to get a paginated list of doors for the selected filters sorted by the passed in sorting option,
Example:
URL: https://www.brandname.com/api/doors/
Parameters:
-
doorType: single | double (optional)
-
selectedSortingOptionId: string (optional)
-
selectedCategoryOptions:
-
Array of:
-
categoryId: string
-
selectedOptionIds: Array<string>
-
-
-
page: number
-
pageSize: number
Result:
In order to deliver a flawless experience to all the users we have implemented a dedicated health check API. The health check API provides the possibility to programmatically ask the DoorVision system if a given visual door is currently enabled in our system. Additionally various health checks of the system itself will be taken into account to make sure that the user always sees the desired door.
The general health check for a customer is available at:
https://server.door-vision.com/api/v1/health/customer
Additionally an external id for a visual door can be appended to make sure this visual door exists (and is enabled) in our system. The visual door health check is available under: https://server.door-vision.com/api/v1/health/customer/<visualDoorExternalId>
Response
The response of the health check is always a JSON object with the following fields:
-
statusCode: The http status code, 200 means a successful health check, every other status code can be considered unhealthy.
-
message: A human readable message which gives additional information
-
error: Optional error message only defined if the status code is not 200
Example response for a successful health check:de of 200).
Example response for an unsuccessful health check:
The HTTP status code of the response itself will be 200 if the system is healthy for the given parameters (customer key and external id of a visual door). Every other HTTP status code should be considered as not healthy.
Usage suggestion
The health check API can be used to decide if the button/link to the DoorVision application should be shown in the Tuereshop/Tuerendirekt webshop. The button or link should only be shown if the health check API returns an healthy response (HTTP status code of 200).
reach out to:
Yannick
Founder & CTO of DoorVision
I'll be happy to assist you with your API to DoorVision. Send me an email at: yannick.schwarenthorer@fluegelspiel.com
