About REST API services

This is for:

In this article

Versioning
Authentication
Accessing the documentation
Services

Coveo for Sitecore deploys public REST services in Sitecore which empower developers to automate configuration tasks.

Versioning

All the services exposed through the /coveo/api route are versioned. If you use it properly, this versioning ensures that your project won’t be impacted by breaking API changes. Therefore, you can update your project to leverage the new API features at your own pace.

To leverage the API versioning, you should follow these best practices:

We strongly recommend that you start your project with the latest available API version. To retrieve the latest version of a specific service, call the version command using the HTTP GET method. Here is an example for the config service:
```
 GET http://<INSTANCE_HOSTNAME>/coveo/api/config/version. HTTP/1.1
```
The response returns this JSON:
```
 { "Latest": 1 }
```
Latest indicates the latest available API version. The version number is one-based, so in this case, the API only exposes the version 1. If the version command returns:
```
 { "Latest": 2 }
```
Both versions 1 and 2 are available.
Now that you know which service version you should use, you have to specify it on the API requests by adding v1 to the URL path.
```
 GET http://<INSTANCE_HOSTNAME>/coveo/api/THE_SERVICE/v1/... HTTP/1.1
```
Later on, when a new version is available, you can update your project to use the new version instead.

Authentication

All the API services use the same authentication methods. Unless specified, all API service calls require that user credentials be provided. The user must either be a Sitecore Administrator or a member of the sitecore\Coveo Admin role.

If the user isn’t properly authorized, the API services will return an HTTP 401 error.

There are two ways to provide the user credentials.

When a Sitecore authentication cookie is present on the API service request, the API service honors it. If the user credentials meet the API call requirements, then the call is executed.

This method is intended for pages hosted in Sitecore that needs to perform API calls using the currently logged in user credentials.

To avoid having to perform a login and attach the authentication cookie to every API request when calling the API service from a script outside the Sitecore instance, you can instead pass a request header.

Method 2: Passing request headers

When calling the API from an external program or script, it’s more convenient to provide the user credentials through the request headers.

This method is secure only if you connect to the Sitecore instance using the HTTPS protocol.

The user credentials must be provided on each API request via the x-scUsername and x-scPassword HTTP headers.

Note

When specifying the x-scUsername header value, make sure to specify the user name in the domain\user format (for example, sitecore\admin).

Accessing the documentation

Each API service is documented using Swagger. All commands are documented, and a user interface is accessible to test the calls.

To populate the Swagger documentation, each service registers itself in the Sitecore initialize pipeline. For example, the Config service uses the InitializeConfigServiceSwagger processor to register its Swagger documentation.

Disabling Swagger documentation for an API service

To disable the Swagger documentation for a specific service, you first have to find the processor that initializes the Swagger documentation. Then, you can patch:delete the processor using an include configuration file.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <initialize>
        <processor type="Coveo.Service.Api.ConfigService.Processors.InitializeConfigServiceSwagger, Coveo.Service.Api.ConfigService">
          <patch:delete />
        </processor>
      </initialize>
    </pipelines>
  </sitecore>
</configuration>

Services

There are two main API services that you can use.

Configuration service

The Config service allows you to configure various Coveo for Sitecore parameters programmatically, such as the Coveo organization and Sitecore credentials.

It’s useful when installing Coveo for Sitecore through scripts.

API Version

GET http://<INSTANCE_HOSTNAME>/coveo/api/config/version HTTP/1.1

Swagger documentation

GET http://<INSTANCE_HOSTNAME>/coveo/api/config/docs/index HTTP/1.1

Index service

The Index service allows you to retrieve information regarding the configured Coveo indexes.

API version

GET http://<INSTANCE_HOSTNAME>/coveo/api/index/version HTTP/1.1

Swagger documentation

GET http://<INSTANCE_HOSTNAME>/coveo/api/index/docs/index HTTP/1.1