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 is10
.offset
: Optional pagination offset. The default value is0
.
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