30 Mar 2018

MultiClusters REST API

What the MultiClusters API does

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.

Quick reference

MultiClusters API

Path Verb Method

/1/clusters

GET List clusters

/1/clusters/mapping/${userID}

GET Get userID

/1/clusters/mapping/top

GET Get top userID

/1/clusters/mapping

GET List userIDs

/1/clusters/mapping/search

POST Search userID

/1/clusters/mapping

POST Assign or Move userID

/1/clusters/mapping/${userID}

DELETE Remove userID

Multi Cluster API

List clusters

Path

/1/clusters

HTTP Verb GET

Description

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

Response

  • clusters (array of object): List of clusters available with an associated number of userIDs, records and data size

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
  },
  
  ]
}

Get userID

Path

/1/clusters/mapping/${userID}

HTTP Verb GET

Description

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
}

Get top userID

Path

/1/clusters/mapping/top

HTTP Verb GET

Description

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
      }
    ],
    ...
  },
  
  ]
}

List userIDs

Path

/1/clusters/mapping

HTTP Verb GET

Description

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
mandatory no
default 0 (start from the beginning)
description

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
  },
  
  ]
}

Search userID

Path

/1/clusters/mapping/search

HTTP Verb POST

Description

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.

Parameters

query
type URL-encoded string
mandatory no
default "" (no fulltext search)
description

query to search inside the userIDs

cluster
type URL-encoded string
mandatory no
default "" (all clusters)
description

Restrict the matching userID to a specific cluster

page
type integer
mandatory no
default 0 (first page)
description

Requested page (zero-based).

histPerPage
type integer
mandatory no
default 20
description

Number of userID to return, the maximum value is 1000.

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
}

Assign or Move userID

Path

/1/clusters/mapping

HTTP Verb POST

Description

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"
}

Remove userID

Path

/1/clusters/mapping/${userID}

HTTP Verb DELETE

Description

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"
}
© Algolia - Privacy Policy