Routes
Routes serve as the middle layer that groups indexes, query pipelines, and levels of access. Through them, users can define which type of search access is granted to users. Routes also provide the ability to search multiple indexes at the same time. The following diagram represents the role and interaction of routes in search.
Three different types of accesses can be provided.
- Public: In this type, access is granted to everybody, even those who do not have a token i.e. end customers with an anonymous token.
- Permission: Only users with proper permission can access these types of routes. 'Permission' is dynamically created while a route is created or updated.
- Customer Specific: In this type of access, customers are granted access to view their data such as order history, cart, and other similar information. Customer ID has to be provided via HTTP header 'X-UpStart-CustomerId'
When a route is created, it is possible to execute operations such as search and suggest dynamically based on configured access. CRUD operations are also available for the management of Routes.
For the sake of example, while creating a route, we will consider the existing query pipeline and filter query rule that was created in the Query Pipeline guide.
To create a route, the following endpoint is used:
POST https://api.upstartcommerce.com/v1/search/routes
It is necessary to define the id of the index but optional to define the query pipeline we want to associate with this route.
The unique id of the route in the example above is set to "hpcharacters". The access level is also defined as "public" in the beginning.
Continuing the example above, the following is the request to search in the route. The following endpoint is used for this purpose.
POST https://api.upstartcommerce.com/v1/search/routes/hpcharacters/search
The following code block represents a snippet of the response generated.
Notice that the "half blood" document in the ancestry is returned in the search results via routes.