APIReferenceSearch

Kentico Kontent Docs - API Reference Search

Overview

Along with the Indexing Service, API Reference Search is a microservice responsible for indexing API reference of the Kentico Kontent documentation portal on the Algolia search engine. It responds to blobs created by Preprocessor and transforms the data from the blob into Algolia-compatible records. Finally, it stores the records in an Azure Blob Storage, where the following Indexing Service can access them.

Specification

Triggers

The service has a single Update EventGrid trigger endpoint:

Update

Event grid trigger, that is used to consume events created when the Preprocessor service creates preprocessed data from an API specification that is stored in Kentico Kontent.

How it works

In order to understand how the API reference data is split into records, read the introduction to Algolia beforehand.

Indexed content types

As described on the Content Models page, API reference consists of multiple content types with text elements that are supposed to be searchable:

• zAPI Specification - Description (Rich Text element), Title, Version (Text elements)
• zAPI Category - Description (Rich Text element), Summary (Text element)
• zAPI Path Operation - Description (Rich Text element), Name (Text element)
• zAPI Response Container - Content (Rich Text element)
• Code sample - Code (Text element)
• Callout - Content (Rich Text element)

Indexable records

Description

Each content item of one of the indexed content types described above always corresponds to at least one record. The most recently encountered heading for each piece of text is being saved in each record (heading attribute), so the web can then redirect the user directly to the anchored heading.

Ideally, there should not be multiple search hits for a single items of type zAPI Category and zAPI Path Operation and all of their children. This is being accomplished by saving the codename of the zAPI Path Category and zAPI Path Operation on each record and setting the codename as a distinct attribute.

Metadata attributes codename, id and section, are used by Index Sync for index management.

objectID is being computed by the API Reference Search and consists of the item's id or when the id would repeat in more records (e.g. callouts that can be used on more places) the objectID consists of the parent item's codename and the item's id. The objectID is required by Algolia and always has to be unique.

Format

{
  "codename": codename of an item from which the record was created (metadata),
  "content": piece of text, (searchable attribute),
  "heading": heading relevant to the piece of text (searchable attribute),
  "id": id of a specific API reference (metadata),
  "section": "API" (metadata) - constant value,
  "title": name of the specific API reference (searchable attribute),
  "objectID": id of the item/codename of parent or id of the item (metadata) - required by Algolia,
}

Example

{
  "codename": "delete_a_content_type",
  "content": "import { ManagementClient } from '@kentico/kontent-management'; const client = new ManagementClient({ projectId: '<YOUR_PROJECT_ID>', apiKey: '<YOUR_API_KEY>'\n}); client.deleteContentType() .byTypeId('269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0') // .byTypeCodename('hosted_video') .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });",
  "heading": "Delete a content type",
  "id": "25f0c6d2-d465-4a58-8fd0-f9e93e436b74",
  "section": "API",
  "title": "Content Management API v2",
  "objectID": "delete_a_content_type##d0feeade-33e0-4835-815c-dadad5648d89"
}

Algorithm

Update endpoint start

The service reacts to blobs created by the Preprocessor service. When creating records from the preprocessed data contained in the blob, the API Reference Search service starts from the zAPI_specification item and proceeds down through its children items. The items are first converted into partial records with sanitized content specified in the Indexed content types section for content types that are supposed to be indexed, all other items are ignored. The partial record consists of codename, content, heading and objectID which are properties specific for each record. After all partial records are created, id, section and title (common for records in one API reference) are added to each record.

Saving to blob storage

When the data is processed and records are created, the service saves the records to a blob storage. It creates a new blob file for each API reference that will be indexed. Alongside the list of records, the blob contains the API reference's codename and id. Additionally, the blob also specifies whether the operation was intialize.

Example output - blob

{
	"codename": "delivery_api",
	"id": "1db12301-a138-44bb-a06a-bc3e655c098a",
	"initialize": false,
	"itemRecords": [
		{
			"codename": "retrieve_a_taxonomy_group_58e62a8",
			"content": "// Tip: Find more about JS/TS SDKs at https://developer.kenticocloud.com/docs/javascript\nimport { DeliveryClient } from 'kentico-cloud-delivery';\n\nconst deliveryClient = new DeliveryClient({\n  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'\n});\n\ndeliveryClient.taxonomy('personas')\n    .toObservable()\n    .subscribe(response => console.log(response.taxonomy));",
			"heading": "Retrieve a taxonomy group",
			"objectID": "retrieve_a_taxonomy_group_58e62a8##c9418d4a-1403-47d5-b289-87aba5ce411b",
			"id": "1db12301-a138-44bb-a06a-bc3e655c098a",
			"section": "API",
			"title": "Delivery API"
		},
		{
			"codename": "retrieve_a_taxonomy_group_58e62a8",
			"content": "Retrieve a specific taxonomy group specified by codename.",
			"heading": "Retrieve a taxonomy group",
			"objectID": "58e62a8b-1953-419e-bcb7-d2b54430b3d2",
			"id": "1db12301-a138-44bb-a06a-bc3e655c098a",
			"section": "API",
			"title": "Delivery API"
		}
	]
}

Configuration for integration tests

Receiving an event from Dispatcher with the "test": "enabled" attribute makes the service run with an alternative set of environment variables that is used for integration tests.