apache-zookeeper-3.5.8.tar.gz

# Licensed to the Apache Software Foundation (ASF) under one or more # contributor license agreements. See the NOTICE file distributed with # this work for additional information regarding copyright ownership. # The ASF licenses this file to You under the Apache License, Version 2.0 # (the "License"); you may not use this file except in compliance with # the License. You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. A REST HTTP gateway for ZooKeeper ================================= Specification Version: 2 ZooKeeper is meant to enable distributed coordination and also store system configuration and other relatively small amounts of information that must be stored in a persistent and consistent manner. The information stored in ZooKeeper is meant to be highly available to a large number of nodes in a distributed-computing cluster. ZooKeeper offers a client-side library that supports rich semantics that include strict ordering guarantees on operations, the creation of ephemeral znodes, and the ability to watch for changes to state. However, where clients need simple "CRUD" (create, read, update, delete) operations, the ZooKeeper libraries can be cumbersome, both to the programmers who have to use them (who are increasingly used to REST-style APIs), and to the operators who have to deploy and update them (for whom deploying and updating client libraries can be very painful). It turns out that most languages comes with client libraries for HTTP that are easy and familiar to program against, and deployed as part of the language runtime. Thus, for simple CRUD clients, an HTTP gateway would be a less cumbersome interface than the ZooKeeper library. This document describes a gatway for using HTTP to interact with a ZooKeeper repository. Binding ZooKeeper to HTTP ------------------------- Encoding -------- UTF-8 unless otherwise noted Paths ----- A ZooKeeper paths are mapped to IRIs and URIs as follows. ZK paths are converted to IRIs by simply percent-encoding any characters in the ZK path that are not allowed in IRI paths. ZK paths are converted to URIs by mapping them first to IRIs, then converting to URIs in the standard way. Going from URIs and IRIs is the reverse of the above but for one difference: any "." and ".." segments in an IRI or URI must be folded before conversion. (Fortunately, ZK does not allow "." and ".." segments in its paths.) ZK and IRIs recommend the same practices when it comes to Unicode normalization: ultimately, normalization is left to application designers, but both recommend that application designers use NFC as a best practice. Root ---- The following examples assume that the ZooKeeper znode heirarchy is bound to the root of the HTTP servers namespace. This may not be the case in practice however, the gateway may bind to some prefix, for example the URL for accessing /a/b/c may be: http://localhost/zookeeper/znodes/v1/a/b/c This is perfectly valid. Users of the REST service should be aware of this fact and code their clients to support any root (in this case "/zookeeper" on the server localhost). Basics: GET, PUT, HEAD, and DELETE ---------------------------------- HTTP's GET, PUT, HEAD, and DELETE operations map naturally to ZooKeeper's "get," "set," "exists," and "delete" operations. ZooKeeper znodes have a version number that changes each time the znode's value is updated. This number is returned by "get," "set," and "exists" operations. The "set" and "delete" operations optionally take a version number. If one is supplied, then "set" or "delete" will fail if the current version of the znode doesn't match the version-number supplied in the call. This mechanism supports atomic read-modify-write cycles. Set/delete requests may include an optional parameter "version" which defaults to no version check. Getting ZooKeeper children -------------------------- We overload the GET method to return the children of a ZooKeeper. In particular, the GET method takes an optional parameter "view" which could be set to one of type values, either "data" or "children". The default is "data". Thus, to get the children of a znode named "/a/b/c", then the GET request should start: GET /znodes/v1/a/b/c?view=children HTTP/1.1 If the requested view is "data", then the data of a znode is returned as described in the previous section. If the requested view is "children", then a list of children is returned in either an XML document, or in a JSON object. (The default is JSON, but this can be controlled changed by setting the Accept header.) Creating a ZooKeeper session ---------------------------- In order to be able to create ephemeral nodes you first need to start a new session. POST /sessions/v1?op=create&expire=<SECONDS> HTTP/1.1 If the session creation is successful, then a 201 code will be returned. A session is just an UUID that you can pass around as a parameter and the REST server will foward your request on the attached persistent connection. Keeping a session alive ----------------------- To keep a session alive you must send hearbeat requests: PUT /sessions/v1/<SESSION-UUID> HTTP/1.1 Closing a ZooKeeper session --------------------------- You can close a connection by sending a DELETE request. DELETE /sessions/v1/<SESSION-UUID> HTTP/1.1 If you don't close a session it will automatically expire after the amount of time you specified on creation. Creating a ZooKeeper znode -------------------------- We use the POST method to create a ZooKeeper znode. For example, to create a znode named "c" under a parent named "/a/b", then the POST request should start: POST /znodes/v1/a/b?op=create&name=c HTTP/1.1 If the creation is successful, then a 201 code will be returned. If it fails, then a number of different codes might be returned (documented in a later subsection). ZooKeeper's create operation has a flag that tells the server to append a sequence-number to the client-supplied znode-name in order to make the znode-name unique. If you set this flag and ask to create a znode named "/a/b/c", and a znode named "/a/b" already exists, then "create" will create a znode named "/a/b/c-#" instead, where "#" is and integer required to generate a unique name in for format %10d. To obtain this behavior, an additional "sequence=true" parameter should be added to the parameters of the POST. (Note that "sequence" is an optional parameter, that defaults to "false"; this default may be provided explicitly if desired.) On success the actual path of the created znode will be returned. If you want to create an ephemeral node you need to specify an additional "ephemeral=true" parameter. (Note that "ephemeral" is an optional parameter, that defaults to "false") (Note: ZooKeeper also allows the client to set ACLs for the newly-created znode. This feature is not currently supported by the HTTP gateway to ZooKeeper.) Content types and negotiation ----------------------------- ZooKeeper REST gateway implementations may support three content-types for request and response messages: * application/octet-stream HEAD - returns nothing (note below: status = 204) GET - returns the znode data as an octet-stream PUT - send binary data, returns nothing POST - send binary data, returns the name of the znode DELETE - returns nothing For PUT and HEAD some other content-type (i.e. JSON or XML) must be used to access the Stat information of a znode. * application/json, application/javascript & application/xml HEAD - returns nothing GET - returns a STAT or CHILD structure PUT - send binary data, returns a STAT structure (sans da