Prev |  | Next

## 24.7. REST endpoint for HA status information

### 24.7.1. Introduction

A common use case for Neo4j HA clusters is to direct all write requests to the master while using slaves for read operations, distributing the read load across the cluster and and gain failover capabilities for your deployment. The most common way to achieve this is to place a load balancer in front of the HA cluster, an example being shown with HA Proxy. As you can see in that guide, it makes use of a REST endpoint to discover which instance is the master and direct write load to it. In this section, we’ll deal with this REST endpoint and explain its semantics.

### 24.7.2. The endpoints

Each HA instance comes with 3 endpoints regarding its HA status. They are complimentary but each may be used depending on your load balancing needs and your production setup. Those are:

- `/db/manage/server/ha/master`
- `/db/manage/server/ha/slave`
- `/db/manage/server/ha/available`

The `/master` and `/slave` endpoints can be used to direct write and non-write traffic respectively to specific instances. This is the optimal way to take advantage of Neo4j’s scaling characteristics. The `/available` endpoint exists for the general case of directing arbitrary request types to instances that are available for transaction processing.

To use the endpoints, perform an HTTP GET operation on either and the following will be returned:

HA REST endpoint responses

Endpoint | Instance State | Returned Code | Body text
--- | --- | --- | ---
`/db/manage/server/ha/master` | Master | `200 OK` | `true`
Slave | `404 Not Found` | `false`
Unknown | `404 Not Found` | `UNKNOWN`
`/db/manage/server/ha/slave` | Master | `404 Not Found` | `false`
Slave | `200 OK` | `true`
Unknown | `404 Not Found` | `UNKNOWN`
`/db/manage/server/ha/available` | Master | `200 OK` | `master`
Slave | `200 OK` | `slave`
Unknown | `404 Not Found` | `UNKNOWN`

### 24.7.3. Examples

From the command line, a common way to ask those endpoints is to use `curl`. With no arguments, `curl` will do an HTTP `GET` on the URI provided and will output the body text, if any. If you also want to get the response code, just add the `-v` flag for verbose output. Here are some examples:

- Requesting `master` endpoint on a running master with verbose output

    #> curl -v localhost:7474/db/manage/server/ha/master
    * About to connect() to localhost port 7474 (#0)
    *   Trying ::1...
    * connected
    * Connected to localhost (::1) port 7474 (#0)
    > GET /db/manage/server/ha/master HTTP/1.1
    > User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
    > Host: localhost:7474
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < Content-Type: text/plain
    < Access-Control-Allow-Origin: *
    < Transfer-Encoding: chunked
    < Server: Jetty(6.1.25)
    <
    * Connection #0 to host localhost left intact
    true* Closing connection #0

- Requesting `slave` endpoint on a running master without verbose output:

    #> curl localhost:7474/db/manage/server/ha/slave
    false

- Finally, requesting the `master` endpoint on a slave with verbose output

    #> curl -v localhost:7475/db/manage/server/ha/master
    * About to connect() to localhost port 7475 (#0)
    *   Trying ::1...
    * connected
    * Connected to localhost (::1) port 7475 (#0)
    > GET /db/manage/server/ha/master HTTP/1.1
    > User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
    > Host: localhost:7475
    > Accept: */*
    >
    < HTTP/1.1 404 Not Found
    < Content-Type: text/plain
    < Access-Control-Allow-Origin: *
    < Transfer-Encoding: chunked
    < Server: Jetty(6.1.25)
    <
    * Connection #0 to host localhost left intact
    false* Closing connection #0

| Unknown status
The `UNKNOWN` status exists to describe when a Neo4j instance is neither master nor slave. For example, the instance could be transitioning between states (master to slave in a recovery scenario or slave being promoted to master in the event of failure). If the `UNKNOWN` status is returned, the client should not treat the instance as a master or a slave and should instead pick another instance in the cluster to use, wait for the instance to transit from the `UNKNOWN` state, or undertake restorative action via systems admin.

Copyright © 2014 Neo Technology

Prev | Up | Next
| Home |