02 Jul 2018

MultiClusters REST API

Overview

Our MultiClusters API makes transparent the difficulties associated with managing multiple clusters by adding a layer on top of the classical API. Here, we describe the REST API tool behind Agolia’s Multi Cluster Management (MCM) feature.

What is Multi Cluster Management (MCM)?

Normally, all of your data can fit onto one cluster. However, when your data becomes too large for one cluster, Algolia offers a way to logically break up your data so that it spans more than one cluster: some users’ data will go on cluster 1, others on cluster 2, and still others on as many clusters as need be.

To find out more on MCM - an overview and use cases, and how it fits within the Algolia infrastructure, plus a tutorial, go here:

The MCM API Client

We’ve developed an API client for MCM for the most common programming languages and platforms. These clients are advanced wrappers on top of the MCM REST API itself and have been made in order to help you to integrate the service within your apps: for both indexing and search. Everything that can be done using the REST API can be done using those clients.

Limitation v0.1

For v0.1, the assignment of users to clusters won’t be automatic: if a user is not properly assigned, or not found, the call will be rejected.

How to get the feature

MCM needs to be enabled on your cluster. You can contact support@algolia.com for more information.

MultiClusters Endpoints

Quick Reference

Verb Path Method

POST

/1/clusters/mapping

Assign or Move userID

GET

/1/clusters/mapping/top

Get top userID

GET

/1/clusters/mapping/${userID}

Get userID

GET

/1/clusters

List clusters

GET

/1/clusters/mapping

List userIDs

DELETE

/1/clusters/mapping/${userID}

Remove userID

POST

/1/clusters/mapping/search

Search userID

Assign or Move userID

Path: /1/clusters/mapping
HTTP Verb: POST
Required API Key ACL: admin API KEY

Description:
Assign or Move a userID to a cluster.

The time it takes to migrate (move) a user is proportional to the amount of data linked to the userID.

Example:

curl -X POST \
     -H "X-Algolia-User-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"cluster\": \"c1-test\"}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK.

A successful response indicates that the operation has been taken into account, and the userID is directly usable.

{
  "createdAt":"2013-01-18T15:33:13.556Z"
}

Get top userID

Path: /1/clusters/mapping/top
HTTP Verb: GET
Required API Key ACL: admin API KEY

Description:
Get the top 10 userIDs with the highest number of records per cluster.

The data returned will usually be a few seconds behind real-time, because userID usage may take up to a few seconds to propagate to the different clusters.

Example:

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/top"

Upon success, the response is 200 OK and contains the following array of userIDs and clusters

{
  "topUsers":[{
    "c1-test-1": [
      {
        "userID": "user1",
        "clusterName": "",
        "nbRecords": 42,
        "dataSize": 0
      }
    ],
    ...
  },
  
  ]
}

Get userID

Path: /1/clusters/mapping/${userID}
HTTP Verb: GET
Required API Key ACL: admin API KEY

Description:
Returns the userID data stored in the mapping.

The data returned will usually be a few seconds behind real-time, because userID usage may take up to a few seconds to propagate to the different clusters.

Example:

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/${USERID}"

Upon success, the response is 200 OK and contains the following userID data

{
  "userID": "user1",
  "clusterName": "c1-test",
  "nbRecords": 42,
  "dataSize":0
}

List clusters

Path: /1/clusters
HTTP Verb: GET
Required API Key ACL: admin API KEY

Description:
List the clusters available in a multi-clusters setup for a single appID

Example:

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters"

Upon success, the response is 200 OK and contains the following clusters

{
  "clusters": [{
    "clusterName": "c1-test",
    "nbRecords": 42,
    "nbUserIDs": 0,
    "dataSize": 0
  },
  
  ]
}

List userIDs

Path: /1/clusters/mapping
HTTP Verb: GET
Required API Key ACL: admin API KEY

Description:
List the userIDs assigned to a multi-clusters appID.

The data returned will usually be a few seconds behind real-time, because userID usage may take up to a few seconds to propagate to the different clusters.

Parameters:

page
type: URL-encoded string
Optional
default: `0` (start from the beginning)

Page to retrieve, the userID per page is by default at 1000 userIDs

Example:

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"page\": 0, \"hitsPerPage\": 20}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK and contains the following userIDs data

{
  "userIDs":[{
    "userID": "user1",
    "clusterName":"c1-test",
    "nbRecords":42,
    "dataSize":0
  },
  
  ]
}

Remove userID

Path: /1/clusters/mapping/${userID}
HTTP Verb: DELETE
Required API Key ACL: admin API KEY

Description:
Remove a userID and its associated data from the multi-clusters.

Example:

curl -X DELETE \
     -H "X-Algolia-USER-ID: ${USER_ID}" \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping"

Upon success, the response is 200 OK and a task is created to remove the userID data and mapping

{
  "deletedAt": "$TIMESTAMP"
}

Search userID

Path: /1/clusters/mapping/search
HTTP Verb: POST
Required API Key ACL: admin API KEY

Description:
Search for userIDs.

The data returned will usually be a few seconds behind real-time, because userID usage may take up to a few seconds propagate to the different clusters.

To keep updates moving quicky, the index of userIDs isn’t built synchronously with the mapping. Instead, the index is built once every 12h, at the same time as the update of userID usage. For example, when you perform a modification like adding or moving a userID, the search will report an outdated value until the next rebuild of the mapping, which takes place every 12h.

Example:

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --data-binary "{ \
     \"query\": \"user1\", \"cluster\":\"c1-test\"}" \
    "https://${APPLICATION_ID}.algolia.net/1/clusters/mapping/search"

Upon success, the response is 200 OK and contains the following userIDs data.

{
  "hits": [{
    "userID": "user1",
    "clusterName": "c1-test",
    "nbRecords": 42,
    "nbUserIDs": 0,
    "dataSize": 0
  },
  
  ],
  "nbHits": 3,
  "updatedAt": 1497522462
}
© Algolia - Privacy Policy