API Complete Reference¶
Payload API Reference¶
API Operations¶
Agents API¶
List agents¶
GET /v1/agents
Parameters¶
Response¶
[
{
"uuid": "5f91c19d-84f0-4122-bc7f-dcdda6704953",
"created_at": "2011-04-22T13:33:48Z",
"project_id": "793491dd5fa8477eb2d6a820193a183b",
"user_id": "02d99a62af974b26b510c3564ba84644",
"updated_at": "2011-04-22T13:33:48Z",
}
]
Queues API¶
Queue Callers API¶
List callers from queue¶
GET /v1/queues/:queue_id/callers
[
{
"created_at": "2011-04-22T13:33:48Z",
"position": 0,
"status": "1",
"updated_at": "2011-04-22T13:33:48Z",
"uuid": "360a5b5ac90149dba0f3f9d4e5abffbc",
}
]
List queues¶
GET /v1/queues
Parameters¶
Response¶
[
{
"uuid": "8090f8b0-4115-11e3-aa6e-0800200c9a66",
"created_at": "2011-04-22T13:33:48Z",
"description": "24/7 Technical support",
"disabled": False,
"name": "support",
"project_id": "793491dd5fa8477eb2d6a820193a183b",
"user_id": "02d99a62af974b26b510c3564ba84644",
"updated_at": "2011-04-22T13:33:48Z",
}
]
Get a single queue¶
GET /v1/queues/:uuid
Parameters¶
Response¶
{
"uuid": "8090f8b0-4115-11e3-aa6e-0800200c9a66",
"created_at": "2011-04-22T13:33:48Z",
"description": "24/7 Technical support",
"disabled": False,
"name": "support",
"project_id": "793491dd5fa8477eb2d6a820193a183b",
"user_id": "02d99a62af974b26b510c3564ba84644",
"updated_at": "2011-04-22T13:33:48Z",
}
Developers Docs¶
Developer Guide¶
Programming HowTos and Tutorials¶
Setting Up a Development Environment¶
Note
This document originates from the OpenStack Nova project. Since we also use the same toolset for testing, we can also use some of their documentaion. We have obviously made changes that only affect our project but we credit the OpenStack project for the original [1].
This page describes how to setup a working Python development environment that can be used in developing payload on Ubuntu. These instructions assume you’re already familiar with git.
Following these instructions will allow you to run the payload unit tests.
Virtual environments¶
payload development uses a set of shell scripts from OpenStack’s DevStack. Virtual enviroments with venv are also available with the source code.
Linux Systems¶
Note
This section is tested for payload on Ubuntu (12.04-64) distribution. Feel free to add notes and change according to your experiences or operating system.
Install the prerequisite packages.
On Ubuntu Precise (12.04):
sudo apt-get install python-dev python-pip git-core redis-server
Getting the code¶
Grab the code from GitHub:
git clone https://github.com/kickstandproject/payload.git
cd payload
Installing and using the virtualenv¶
To install the virtual environment you simply run the following:
python tools/install_venv.py
This will install all of the Python packages listed in the requirements.txt file into your virtualenv. There will also be some additional packages (pip, distribute, greenlet) that are installed by the tools/install_venv.py file into the virutalenv.
If all goes well, you should get a message something like this:
payload development environment setup is complete.
payload development uses virtualenv to track and manage Python dependencies
while in development and testing.
To activate the payload virtualenv for the extent of your current shell
session you can run:
$ source .venv/bin/activate
Or, if you prefer, you can run commands in the virtualenv on a case by case
basis by running:
$ tools/with_venv.sh <your command>
Also, make test will automatically use the virtualenv.
Running unit tests¶
The unit tests will run by default inside tox env in the .tox directory. Run the unit tests by doing:
tox
See Unit Tests for more details.
Contributing Your Work¶
Once your work is complete you may wish to contribute it to the project. Refer to HowToContribute for information. Nova uses the Gerrit code review system. For information on how to submit your branch to Gerrit, see GerritWorkflow.
Footnotes
[1] | See http://docs.openstack.org/developer/nova/devref/development.environment.html |
Unit Tests¶
Note
This document originates from the OpenStack Nova project. Since we also use the same toolset for testing, we can also use some of their documentaion. We have obviously made changes that only affect our project but we credit the OpenStack project for the original [1].
Payload contains a suite of unit tests, in the payload/tests directory.
Any proposed code change will be automatically rejected by the Kickstand Project Jenkins server if the change causes unit test failures.
Running the tests¶
Run the unit tests by doing:
tox
This script is a wrapper around the nose testrunner and the pep8 checker.
Footnotes
[1] | See http://docs.openstack.org/developer/nova/devref/unit_tests.html |
Man pages¶
payload-api¶
payload-manage¶
Control and manage payload¶
Author: | paul.belanger@polybeacon.com |
---|---|
Date: | May 12, 2014 |
Copyright: | PolyBeacon, Inc |
Version: | |
Manual section: | 1 |
SYNOPSIS¶
payload-manage <category> <action> [<args>]
DESCRIPTION¶
payload-manage is a CLI tool to control payload
OPTIONS¶
General options
payload DB¶
payload-manage db sync
Sync the database up to the most recent version.
payload-manage db version
Print the current database version.
FILES¶
- /etc/payload/payload.conf
Modules¶
payload¶
payload Package¶
payload Package¶
test Module¶
- class payload.test.Database(db_session, db_migrate, sql_connection, sqlite_db, sqlite_clean_db)¶
Bases: fixtures.fixture.Fixture
- setUp()¶
- class payload.test.TestCase(*args, **kwargs)¶
Bases: testtools.testcase.TestCase
Test case base class for all unit tests.
- config(**kw)¶
Override some configuration values.
The keyword arguments are the names of configuration options to override and their values.
If a group argument is supplied, the overrides are applied to the specified configuration option group.
All overrides are automatically cleared at the end of the current test by the fixtures cleanup process.
- path_get(project_file=None)¶
Get the absolute path to a file. Used for testing the API.
Parameters: project_file – File whose path to return. Default: None. Returns: path to the specified file, or path to project root.
- setUp()¶
Run before each method to initialize test environment.
version Module¶
Subpackages¶
api Package¶
api Package¶
app Module¶
- class payload.api.app.VersionSelectorApplication¶
Bases: object
- payload.api.app.app_factory(global_config, **local_conf)¶
- payload.api.app.build_server()¶
- payload.api.app.get_handler_cls()¶
- payload.api.app.get_pecan_config()¶
- payload.api.app.get_server_cls(host)¶
Return an appropriate WSGI server class base on provided host
Parameters: host – The listen host for the ceilometer API server.
- payload.api.app.load_app()¶
- payload.api.app.setup_app(pecan_config=None)¶
config Module¶
hooks Module¶
middleware Module¶
Middleware to replace the plain text message body of an error response with one formatted so the client can parse it.
Based on pecan.middleware.errordocument
- class payload.api.middleware.ParsableErrorMiddleware(app)¶
Bases: object
Replace error body with something the client can parse.
Subpackages¶
- class payload.api.controllers.v1.agent.Agent(**kwargs)¶
Bases: payload.api.controllers.v1.base.APIBase
API representation of an agent.
- created_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- project_id¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- updated_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- user_id¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- uuid¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- class payload.api.controllers.v1.agent.AgentsController¶
Bases: pecan.rest.RestController
REST Controller for Agents.
- delete(*args, **kwargs)¶
Delete an agent.
- get_all(*args, **kwargs)¶
Retrieve a list of agents.
- get_one(*args, **kwargs)¶
Retrieve information about the given agent.
- post(*args, **kwargs)¶
Create a new agent.
- put(*args, **kwargs)¶
Update an existing agent.
- class payload.api.controllers.v1.base.APIBase(**kw)¶
Bases: wsme.types.Base
- as_dict()¶
- created_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- updated_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- class payload.api.controllers.v1.controller.Controller¶
Bases: object
- agents = <payload.api.controllers.v1.agent.AgentsController object at 0x30c8710>¶
- queues = <payload.api.controllers.v1.queue.QueuesController object at 0x30c8850>¶
- schemas = <payload.api.controllers.v1.schema.SchemasController object at 0x30c8890>¶
- class payload.api.controllers.v1.queue.Queue(**kwargs)¶
Bases: payload.api.controllers.v1.base.APIBase
API representation of a queue.
- created_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- description¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- disabled¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- name¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- project_id¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- updated_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- user_id¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- uuid¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- class payload.api.controllers.v1.queue.QueuesController¶
Bases: pecan.rest.RestController
REST Controller for queues.
- callers = <payload.api.controllers.v1.queue.caller.QueueCallersController object at 0x30c3b50>¶
- delete(*args, **kwargs)¶
Delete a queue.
- get_all(*args, **kwargs)¶
Retrieve a list of queues.
- get_one(*args, **kwargs)¶
Retrieve information about the given queue.
- members = <payload.api.controllers.v1.queue.member.QueueMembersController object at 0x30c8150>¶
- post(*args, **kwargs)¶
Create a new queue.
- put(*args, **kwargs)¶
- stats = <payload.api.controllers.v1.queue.stat.QueueStatsController object at 0x30c8190>¶
- class payload.api.controllers.v1.queue.caller.QueueCallersController¶
Bases: pecan.rest.RestController
REST Controller for queue callers.
- delete(*args, **kwargs)¶
Delete a queue caller.
- get_all(*args, **kwargs)¶
Retrieve a list of queue callers.
- get_one(*args, **kwargs)¶
Retrieve information about the given queue.
- post(*args, **kwargs)¶
Create a new queue caller.
- class payload.api.controllers.v1.queue.member.QueueMember(**kwargs)¶
Bases: payload.api.controllers.v1.base.APIBase
API representation of a queue member.
- agent_uuid¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- created_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- queue_uuid¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- updated_at¶
Complex type attribute definition.
Example:
class MyComplexType(wsme.types.Base): optionalvalue = int mandatoryvalue = wsattr(int, mandatory=True) named_value = wsattr(int, name='named.value')
After inspection, the non-wsattr attributes will be replaced, and the above class will be equivalent to:
class MyComplexType(wsme.types.Base): optionalvalue = wsattr(int) mandatoryvalue = wsattr(int, mandatory=True)
- class payload.api.controllers.v1.queue.member.QueueMembersController¶
Bases: pecan.rest.RestController
REST Controller for queue members.
- delete(*args, **kwargs)¶
Delete a queue member.
- get_all(*args, **kwargs)¶
Retrieve a list of queue members.
- get_one(*args, **kwargs)¶
Retrieve information about the given queue member.
- post(*args, **kwargs)¶
Create a new queue member.
cmd Package¶
cmd Package¶
manage Module¶
CLI interface for payload management.
- payload.cmd.manage.add_command_parsers(subparsers)¶
- payload.cmd.manage.do_db_sync()¶
Place a database under migration control and upgrade, creating first if necessary.
- payload.cmd.manage.do_db_version()¶
Print database’s current migration level.
- payload.cmd.manage.main()¶
common Package¶
common Package¶
exception Module¶
Payload base exception handling.
- exception payload.common.exception.AgentNotFound(message=None, **kwargs)¶
Bases: payload.common.exception.NotFound
- message = 'Agent %(uuid)s could not be found'¶
- exception payload.common.exception.NotFound(message=None, **kwargs)¶
Bases: payload.common.exception.PayloadException
- code = 404¶
- message = 'Resource could not be found'¶
- exception payload.common.exception.PayloadException(message=None, **kwargs)¶
Bases: exceptions.Exception
Base Payload Exception
To correctly use this class, inherit from it and define a ‘message’ property. That message will get printf’d with the keyword arguments provided to the constructor.
- code = 500¶
- format_message()¶
- headers = {}¶
- message = 'An unknown exception occurred.'¶
- safe = False¶
- exception payload.common.exception.QueueCallerNotFound(message=None, **kwargs)¶
Bases: payload.common.exception.NotFound
- message = 'Queue caller %(caller_id)s could not be found'¶
- exception payload.common.exception.QueueMemberDuplicated(message=None, **kwargs)¶
Bases: payload.common.exception.PayloadException
- message = 'Queue member %(uuid)s already exists.'¶
- exception payload.common.exception.QueueMemberNotFound(message=None, **kwargs)¶
Bases: payload.common.exception.NotFound
- message = 'Queue member %(uuid)s could not be found'¶
- exception payload.common.exception.QueueNotFound(message=None, **kwargs)¶
Bases: payload.common.exception.NotFound
- message = 'Queue %(uuid)s could not be found'¶
paths Module¶
- payload.common.paths.basedir_def(*args)¶
Return an uninterpolated path relative to $pybasedir.
- payload.common.paths.basedir_rel(*args)¶
Return a path relative to $pybasedir.
- payload.common.paths.bindir_def(*args)¶
Return an uninterpolated path relative to $bindir.
- payload.common.paths.bindir_rel(*args)¶
Return a path relative to $bindir.
- payload.common.paths.state_path_def(*args)¶
Return an uninterpolated path relative to $state_path.
- payload.common.paths.state_path_rel(*args)¶
Return a path relative to $state_path.
db Package¶
db Package¶
api Module¶
- payload.db.api.create_agent(user_id, project_id)¶
Create a new agent.
- payload.db.api.create_queue(name, user_id, project_id, description='', disabled=False)¶
Create a new queue.
- payload.db.api.create_queue_member(agent_uuid, queue_uuid)¶
Create a new queue member.
- payload.db.api.delete_agent(uuid)¶
Delete an agent.
- payload.db.api.delete_queue(uuid)¶
Delete a queue.
- payload.db.api.delete_queue_member(agent_uuid, queue_uuid)¶
Delete a queue member.
- payload.db.api.get_agent(uuid)¶
Retrieve information about the given agent.
- payload.db.api.get_queue(uuid)¶
Retrieve information about the given queue.
- payload.db.api.get_queue_member(agent_uuid, queue_uuid)¶
Retrieve information about the given queue member.
- payload.db.api.list_agents()¶
Retrieve a list of agents.
- payload.db.api.list_queue_members(uuid)¶
Retrieve a list of queue members.
- payload.db.api.list_queues()¶
Retrieve a list of queues.
middleware Package¶
middleware Package¶
api Module¶
- class payload.middleware.api.Connection¶
Bases: object
- create_queue_caller(queue_id, values)¶
- create_queue_member(agent_id, queue_id, values)¶
- delete_queue_caller(queue_id, uuid)¶
- get_queue_caller(queue_id, uuid)¶
Retrieve information about the given queue caller.
- get_queue_member(agent_id, queue_id)¶
Retrieve information about the given queue member.
- get_queue_stats(queue_id)¶
Retrieve stats for a queue.
- list_queue_callers(queue_id, status=None)¶
Retrieve a list of queue callers.
- list_queue_members(queue_id, status=None)¶
Retrieve a list of queue members.
- class payload.middleware.api.QueueCallerStatus¶
Bases: object
- HUNGUP = 4¶
- ONCALL = 3¶
- ONHOLD = 1¶
- RINGING = 2¶
- payload.middleware.api.get_instance()¶
Return a DB API instance.