Querying and Searching Content Hub Programmatically

Introduction

Content Hub provides powerful yet simple yet powerful REST API, enabling clients to query (http://{{hostname}}/api/query) and search (http://{{hostname}}/api/search) for content in a given Content Hub instance. .NET client application can take advantage of Sitecore's WebClient SDK, which is a set of wrapper libraries, available as NuGet and NPM packages. This article is a high level "getting started" guide with may links to Sitecore documentation and Postman collection with a few sample REST calls.

NuGet and NPM packages are linked on this page).

Authentication for REST API calls

Content Hub API users must be authenticated in order to be able to interact with Content Hub content, so I'll start with this step. Authentication endpoint takes username and password as parameters and returns an authentication token as a string. The issued token will remain valid until a new token is generated. This token needs to be sent in the X-Auth-Token header of every request that requires authentication, all API calls described below will require this authentication token to be present.

Authentication call is a POST to https://{{hostname}}/api/authenticate with the body, containing existing user's username and password like so:

{
	"user_name":"{{username}}",
	"password":"{{password}}"
}

"Get token" documentation

Querying with Content Hub REST API

Querying is a feature of Sitecore Content Hub that allows a user to query for specific entities using specific indexed metadata fields. This basic querying is contrasted against the more elaborate search functionality offered by the M.Content API (more on search below).

All query requests follow this pattern:

GET [http://hostname/api/entities/entities/query?query={{query expressions}}](http://hostname/api/entities/entities/query?query={{query expressions}})

Where {{query expressions}} is one or more expressions, in the following format:

DATATYPE('PropertyName') OPERATOR PropertyValue

Where

DATATYPE can be one of the following: String, Integer, Long, Decimal, Float, Datetime
OPERATOR values can be one of the following: == (equal), != (not equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal)

Sitecore Content Hub documentation explains this well and includes some good query examples.

I'm including the link to the Postman collection, which has enough examples to help getting started with queries.

TODO: add the link to the Postman collection

Querying with WebClient SDK

Just like with REST API clients, callers using WebClient must first be authenticated in order to make query or search calls. WebClient provides two authentication options, (following links point to Sitecore documentation):

Query Code Example

Below is some sample code, showing the most basic use cases of sending the query request and then iterating through results. Content Hub documentation covers these topics in much greater detail.

using System.Linq;
using Stylelabs.M.Base.Querying;
using Stylelabs.M.Base.Querying.Linq;


var query = Query.CreateQuery(entities =>
   from e in entities
   where [conditions]
   orderby [property] ascending | descending
   select e);


//Get single query result
IEntity entity = await client.Querying.SingleAsync(query);

//Query for single entity Id 
long? entityId = await client.Querying.SingleIdAsync(query);

//Get multiple query results
IEntityQueryResult queryResult = await client.Querying.QueryAsync(query);

//Create iterator and iterate through multiple Entity results
IEntityIterator iterator = client.Querying.CreateEntityIterator(query);

while (await iterator.MoveNextAsync())
{
   var entities = iterator.Current.Items;
   // Do something with the entities
}


//Query for multiple IDs 
IIdQueryResult queryResult = await client.Querying.QueryIdsAsync(query);

//Create iterator and iterate through multiple Id results
IIdIterator iterator = client.Querying.CreateIdIterator(query);

while (await iterator.MoveNextAsync())
{
   var ids = iterator.Current.Items;
   // Do something with the ids
}

Search

The search API exposes a more elaborate search functionality offered by the M.Content API. Search API is relying on facets and filters defined via code or in Content Hub's portal configuration settings (more details in Sitecore Content Hub documentation),

A typical API call would look like this:

GET http://hostname/api/search?q=myQuery&skip=3&take=10

The response will include search results along with addQuery value, which is a serialized and encoded query that has all query arguments added, so any subsequent calls (e.g. for extra faceting, sorting, paging, etc.) can use the returned query to build on. Again, I'd rather defer to Sitecore Content Hub documentation for further details as it explains the search well and provides some good examples.

References

Creating queries with LINQ

Querying client

Getting started with Web Client SDK

Postman collection with search examples

Note: make sure to replace {{hostname}} with one of your Content Hub instance and {{Entity ID}} as needed. {{TODO: add GIT link to Postman collection and environment files. Provide instructions on how to configure Postman Environment}}