2 min read

How to use the Index API

The Index API is a crucial component of Empathy Platform's suite of APIs since it facilitates one of the most important steps in creating an exceptional search and discovery experience.

Understanding and utilizing the Index API is valuable for developers working with Empathy Platform as it enables efficient search data management, ensures data consistency, and provides the flexibility needed to handle evolving product catalogs in commerce stores and other search-based applications.

You can use the Index API for several tasks. The following are the most common uses related to the Index Builder, which is in charge of managing the feed transformation:

Use these base URLs for each case:

  • Staging environment: https://api.staging.empathy.co/index/v1
  • Production environment: https://api.empathy.co/index/v1

Getting a job

To return the information of the job, use the following request:

  • GET jobs/{siteId}/{indexToken}/job/{indexJobId}

Path parameters:

  • siteId: Identifier of the client.
  • indexToken: Client index token.
  • indexJobId: Identifier of the job.

Job result example:

{
  "id": "5f05852ed5294f84c88d7bca",
  "siteId": "thisClient",
  "feedId": "catalog",
  "bucketName": "eb-feeds-998htgkm",
  "bucketPath": "test_k/",
  "priority": 0,
  "state": "QUEUED",
  "date": "2020-07-08T08:34:54Z",
  "updatedAt": "2020-07-08T08:34:54Z",
  "opType": "FULL",
  "metrics": {
    "rTime": 0,
    "wTime": 0,
    "tTime": 0,
    "wProcessed": 0,
    "rProcessed": 0
  },
  "version": 1590969600000,
  "transitions": [
    {
      "state": "QUEUED",
      "date": "2020-07-08T08:34:54Z"
    }
  ]
}

Listing jobs

To return an array of all jobs associated with a client token, use the following request:

  • GET jobs/{siteId}/{indexToken}

Path parameters:

  • siteId: Identifier of the client.
  • indexToken: Client index token.

If both siteId and indexToken are informed, the system checks if the values are correlative. Otherwise, a 403 error is returned.

Query parameters:

  • size: Optional pagination size. The default value is 10.
  • offset: Optional pagination offset. The default value is 0.

Submitting a job

To create a new job to index new content, use the following request:

  • POST jobs/submit/{siteId}/{indexToken}/{feedId}

Path parameters:

  • siteId: Identifier of the client.
  • indexToken: Client index token.
  • feedId: Identifier of the feed to filter the jobs, for example, catalog.

This also takes the feed file as InputStream to be indexed.

Query parameters:

It expects a pivots URL parameter to be present, showing the pivots to be used for the request: &pivots=lang,store&lang=en&store=12345

The pivots parameter indicates the dynamic parameters the API should consider.

If both siteId and clientToken are informed, the system checks if the values are correlative. Otherwise, a 403 error is returned.

Canceling jobs

To cancel a QUEUED job, use the following request:

  • DELETE jobs/{siteId}/{indexToken}/{jobId}

Path parameters:

  • siteId: Identifier of the client.
  • indexToken: Client index token.
  • jobId: Identifier of the job to reimport.

If both siteId and clientToken are informed, the system checks if the values are correlative. Otherwise, a 403 error is returned.

warning

When the status of the job is RUNNING, you cannot cancel the job.

Checking status

You can check the status and get information on the service:

Health

Check whether the service is up and running. If it is, the response is OK:

  • GET status/health

Info

Get the environment variables that the service is using to run.

  • GET status/info