To customize and start the Coveo Search API

1. Using an administrator account, connect to the server on which the Coveo Search API is installed.

2. Using a text editor, open the [Search_API_Install_Path]\config.yml file (by default C:\Program Files\Coveo Search API 8\config.yml).

3. In the server section of the file:

   Example: The Coveo Search API is installed on the same server as CES (myCoveoMasterServer) and uses the default port (52810).

   server:
     uri: https://myCoveoMasterServer:52810
     serverCertificatePath: E:\CES70\Config\Certificates\cert-ca.pem
     clientCertificatePath: E:\CES70\Config\Certificates\cert-iis.p12

   1. For the uri parameter, enter the URI of your Coveo Master server (where Coveo Enterprise Search is installed) hosting the unified index with which you want this REST API to send query and receive search results.

      When the Coveo Search API is on the same server as CES, the default uri (https://localhost:52810) will work.

      When your Coveo Master server is not using the default service port (52810), enter the port it uses.

   2. For the serverCertificatePath and clientCertificatePath parameters, enter the local path where respectively the CES server and client certificates can be found. The REST API will use these certificates to authenticate itself with the index server.

      Note: When the Coveo Search API is on a different server than CES, you must copy the certificate files from the Coveo Master server (typically from the [Index_Path]\Config\Certificates\ folder to the path you enter on the server where the Coveo Search API is installed).

4. In the basicAuthentication, windowsAuthentication, and guest sections of the file, determine if and how users performing the search must be authenticated to be authorized to get results from the API: 

   Example: With this configuration, only Active Directory users can get results.

   basicAuthentication:
     enabled: false
     provider: Active Directory
   
   windowsAuthentication:
     enabled: true
     provider: Active Directory
   
   guest:
     enabled: false
     name: DOMAIN\user
     provider: Active Directory

   1. For the enabled parameter, enter true when you want to enable this authentication mode.

      Note: basicAuthentication passes credentials in clear text so it should always be used with secured HTTPS (SSL) connections or only for internal tests.

   2. For the provider parameter, enter the name of the security provider that CES will use to validate the authentication.

      Note: You can find the security provider name in the CES Administration Tool Security Providers page.

   Example: When the API can be accessed publicly by anyone, you can enable the guest authentication mode for the S-1-1-0 Windows (Active Directory) Everyone well-known security identifier group.

   guest:
     enabled: true
     name: S-1-1-0
     provider: Active Directory
     type: Group

5. When one or more Web application will use this API, identify tokens/GUIDs that applications will need to provide to be authorized to use the API and that you will communicate only to trusted parties (see On-Premises Search Token Authentication):

   Example: The search interfaces from your Web site and your Intranet use this API.

   tokens:
     sharedKey: a0534332-f093-4064-a712-4a79a97c9227
   
   applications:
     - name: Website search
       secret: 353c7d37-7445-4217-a0ba-52c772c05632
       allowImpersonate: false
     - name: Intranet search
       secret: 8eSHODDPqGiMvqVY4vwNDut7sdRgwhovSQlAWDLr1nTwSzJi2lDiK
       allowImpersonate: false

   1. In the tokens section of the file, the sharedKey parameter needs to be set only in specific cases (see Configuring Search Token Generation). When this is the case, generate and enter a GUID to be used as a shared key token.

   2. In the applications section of the file, create one subsection starting with a dash for each application that you want to authorize to use this API: 

      1. For the name parameter, enter a name of your choice that will identify the application. This name is only for your reference in this file.

      2. For the secret parameter, generate and enter a GUID to be used as the application secret token.

      3. For the allowImpersonate parameter, leave to false unless the application needs to perform search on behalf of someone else without having to supply the password.

         Example: With Coveo for Salesforce, the user that performs a search is authenticated in Salesforce. The search application gets the user Salesforce account (email) and is set to impersonate this user to only return documents that this user has the permissions to see.

6. Save the file.

   Note: You can add many other parameters to more specifically control how your Coveo Search API operates (see Windows Service Configuration File).

7. Start the Coveo Search API service:

   1. Open the Windows Services management console.

   2. Locate and right-click the Coveo Search API service, and then click Start.

   3. Ensure that the service starts.

      Note: The service immediately stops if the config.yml file contains a syntax error such as a tab character that is an invalid character in the YAML format (see REST Search API Windows Service Stops).

8. You can validate that the service is accessible from various computers:

   1. Using a browser, access the URL in the following format:

      http://[REST_API_SERVER]:[port]/rest/search

      Examples:

      • From the same server when the port is the default (8080):

        http://localhost/rest/search

      • From another computer when the port is not the default:

        http://myRestApiServer:80/rest/search

   2. Validate that the REST API JSON response appears in the browser.