217 lines
6.0 KiB
ReStructuredText
217 lines
6.0 KiB
ReStructuredText
..
|
|
Licensed 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.
|
|
|
|
=============================================
|
|
Welcome to the Zaqar Developer Documentation!
|
|
=============================================
|
|
|
|
Zaqar is a multi-tenant cloud messaging and notification service for web
|
|
and mobile developers.
|
|
|
|
The service features a REST API, which developers can use to send messages
|
|
between various components of their SaaS and mobile applications, by using a
|
|
variety of communication patterns. Underlying this API is an efficient
|
|
messaging engine designed with scalability and security in mind. The Websocket
|
|
API is also available.
|
|
|
|
Other OpenStack components can integrate with Zaqar to surface events to end
|
|
users and to communicate with guest agents that run in the "over-cloud" layer.
|
|
|
|
.. note:: This documentation is generated by the Sphinx toolkit and lives in
|
|
the Zaqar project source tree. Additional draft and project documentation
|
|
regarding Zaqar and other components of OpenStack can be found on the
|
|
`OpenStack Wiki`_, as well as in the user guides found on
|
|
`docs.openstack.org`_.
|
|
|
|
.. _`OpenStack Wiki`: http://wiki.openstack.org
|
|
.. _`docs.openstack.org`: http://docs.openstack.org
|
|
|
|
Key features
|
|
============
|
|
|
|
Zaqar provides the following key features:
|
|
|
|
* Choice between two communication transports. Both with Keystone support:
|
|
|
|
* Firewall-friendly, **HTTP-based RESTful API**. Many of today's developers
|
|
prefer a more web-friendly HTTP API. They value the simplicity and
|
|
transparency of the protocol, it's firewall-friendly nature, and it's huge
|
|
ecosystem of tools, load balancers and proxies. In addition, cloud
|
|
operators appreciate the scalability aspects of the REST architectural
|
|
style.
|
|
* **Websocket-based API** for persistent connections. Websocket protocol
|
|
provides communication over persistent connections. Unlike HTTP, where
|
|
new connections are opened for each request/response pair, Websocket can
|
|
transfer multiple requests/responses over single TCP connection. It saves
|
|
much network traffic and minimizes delays.
|
|
|
|
* Multi-tenant queues based on Keystone project IDs.
|
|
* Support for several common patterns including event broadcasting, task
|
|
distribution, and point-to-point messaging.
|
|
* Component-based architecture with support for custom backends and message
|
|
filters.
|
|
* Efficient reference implementation with an eye toward low latency and high
|
|
throughput (dependent on backend).
|
|
* Highly-available and horizontally scalable.
|
|
* Support for subscriptions to queues. Several notification types are
|
|
available:
|
|
|
|
* Email notifications.
|
|
* Webhook notifications.
|
|
* Websocket notifications.
|
|
|
|
Project scope
|
|
=============
|
|
|
|
The Zaqar API is data-oriented. That is, it does not provision message brokers
|
|
and expose those directly to clients. Instead, the API acts as a bridge between
|
|
the client and one or more backends. A provisioning service for message
|
|
brokers, however useful, serves a somewhat different market from what Zaqar is
|
|
targeting today. With that in mind, if users are interested in a broker
|
|
provisioning service, the community should consider starting a new project to
|
|
address that need.
|
|
|
|
Design principles
|
|
=================
|
|
|
|
Zaqar, as with all OpenStack projects, is designed with the following
|
|
guidelines in mind:
|
|
|
|
* **Component-based architecture.** Quickly add new behaviors
|
|
* **Highly available and scalable.** Scale to very serious workloads
|
|
* **Fault tolerant.** Isolated processes avoid cascading failures
|
|
* **Recoverable.** Failures should be easy to diagnose, debug, and rectify
|
|
* **Open standards.** Be a reference implementation for a community-driven
|
|
|
|
Concepts
|
|
========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
glossary
|
|
|
|
Modules reference
|
|
=================
|
|
|
|
Zaqar is composed of two layers:
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
transport
|
|
storage/autoindex
|
|
|
|
The **transport drivers** are responsible for interacting with Zaqar clients.
|
|
Every query made by clients is processed by the transport layer, which is in
|
|
charge of passing this information to the backend and then returning the
|
|
response in a format understandable by the client.
|
|
|
|
The **storage drivers** are responsible for interacting with the storage
|
|
backends and, that way, store or retrieve the data coming from the transport
|
|
layer.
|
|
|
|
In order to keep these layers decoupled, we have established that
|
|
**checks should be performed in the appropriate layer**. In other words,
|
|
transport drivers must guarantee that the incoming data is well-formed and
|
|
storage drivers must enforce their data model stays consistent.
|
|
|
|
User Guide
|
|
==========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
getting_started
|
|
send_request_api.rst
|
|
authentication_tokens.rst
|
|
headers_queue_api_working.rst
|
|
|
|
Setting up Zaqar in development environment
|
|
===========================================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
devref/development.environment
|
|
|
|
Welcome new contributors
|
|
========================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
welcome
|
|
first_patch
|
|
first_review
|
|
|
|
Running and writing tests
|
|
=========================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
running_tests
|
|
test_suite
|
|
|
|
Reviewing
|
|
=========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
reviewer_guide
|
|
|
|
Tutorials
|
|
=========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
running_benchmark
|
|
writing_pipeline_stages
|
|
|
|
Feature Guide
|
|
=============
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
subscription_confirm
|
|
OSprofiler
|
|
|
|
Other resources
|
|
===============
|
|
|
|
.. toctree::
|
|
:maxdepth: 3
|
|
|
|
launchpad
|
|
gerrit
|
|
jenkins
|
|
|
|
Internal API reference
|
|
======================
|
|
|
|
.. toctree::
|
|
:maxdepth: 3
|
|
|
|
api/autoindex
|
|
|
|
Indices and tables
|
|
------------------
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|