Commit 5cd5d891 authored by Daniele Venzano's avatar Daniele Venzano

Expand the documentation, in particular about the client API

parent 235ba4c1
......@@ -17,5 +17,8 @@ API documentation
:maxdepth: 2
developer/introduction
developer/client
developer/rest-api
developer/auth.rst
developer/api-endpoint
developer/master-api
developer/scheduler
Internal API enpoint
====================
.. automodule:: zoe_api.api_endpoint
:members:
Auth modules
============
.. automodule:: zoe_api.auth.base
:members:
.. automodule:: zoe_api.auth.file
:members:
.. automodule:: zoe_api.auth.ldap
:members:
Internal API with the Zoe master
================================
.. automodule:: zoe_api.master_api
:members:
REST API classes
================
.. automodule:: zoe_api.rest_api.discovery
:members:
.. automodule:: zoe_api.rest_api.execution
:members:
.. automodule:: zoe_api.rest_api.info
:members:
.. automodule:: zoe_api.rest_api.service
:members:
.. automodule:: zoe_api.rest_api.statistics
:members:
.. automodule:: zoe_api.rest_api.utils
:members:
......@@ -39,6 +39,7 @@ Contents:
monitoring
architecture
howto_zapp
rest-api
vision
roadmap
contributing
......
.. _rest-api:
Zoe REST API
============
Zoe can be used from the command line or the web interface. For more complex tasks also an API is provided, so that Zoe functionality can be accesses programmatically.
The API is provided by the zoe-api processes, on the same port of the web interface (5001 by default). Every URL of the API contains, after the hostname and port, the path ``/api/<api version>/``. This document describes API version 0.6.
Info endpoint
-------------
This endpoint does not need authentication. It returns general, static, information about the Zoe software. It is meant for checking that the client is able to talk correctly to the API server::
curl http://bf5:8080/api/0.6/info | json_pp
Will return a JSON document, like this::
{
"version" : "0.10.1-beta",
"deployment_name" : "prod",
"application_format_version" : 2,
"api_version" : "0.6"
}
Where:
* ``version`` is the Zoe version
* ``deployment_name`` is the name configured for this deployment (multiple Zoe deployment can share the same cluster)
* ``application_format_version`` is the version of ZApp format this Zoe is able to understand
* ``api_version`` is the API version supported by this Zoe and should match the one used in the request URL
Execution endpoint
------------------
r'/execution/([0-9]+)', ExecutionAPI, route_args),
tornado.web.url(API_PATH + r'/execution/delete/([0-9]+)', ExecutionDeleteAPI, route_args),
tornado.web.url(API_PATH + r'/execution', ExecutionCollectionAPI, route_args),
Service endpoint
----------------
tornado.web.url(API_PATH + r'/service/([0-9]+)', ServiceAPI, route_args),
tornado.web.url(API_PATH + r'/service/logs/([0-9]+)', ServiceLogsAPI, route_args),
Discovery endpoint
------------------
This endpoint does not need authentication. It returns a list of services that meet the criteria passed in the URL. It can be used as a service discovery mechanism for those ZApps that need to know in advance the list of available services.
Request::
curl http://bf5:8080/api/0.6/discovery/by_group/<execution_id>/<service_type> | json_pp
Where:
* ``execution_id`` is the numeric ID of the execution we need to query
* ``service_type`` is the service name (as defined in the ZApp) to filter only services of that type
Will return a JSON document, like this::
{
"service_type" : "boinc-client",
"execution_id" : "23015",
"dns_names" : [
"boinc-client0-23015-prod"
]
}
Where:
* ``service_type`` is the name of the service as passed in the URL
* ``execution_id`` is the execution ID as passed in the URL
* ``dns_names`` is the list of DNS names for each service instance currently active (only one in the example above)
Statistics endpoint
-------------------
This endpoint does not need authentication. It returns current statistics about the internal Zoe status.
Scheduler
^^^^^^^^^
Request::
curl http://bf5:8080/api/0.6/statistics/scheduler | json_pp
Will return a JSON document, like this::
{
"termination_threads_count" : 0,
"queue_length" : 0
}
Where:
* ``termination_threads_count`` is the number of executions that are pending for termination and cleanup
* ``queue_length`` is the number of executions in the queue waiting to be started
......@@ -45,7 +45,6 @@ class ExecutionAPI(RequestHandler):
Terminate an execution.
:param execution_id: the execution to be terminated
:return:
"""
uid, role = get_auth(self)
......@@ -73,7 +72,6 @@ class ExecutionDeleteAPI(RequestHandler):
Delete an execution.
:param execution_id: the execution to be deleted
:return:
"""
uid, role = get_auth(self)
......@@ -111,6 +109,7 @@ class ExecutionCollectionAPI(RequestHandler):
def post(self):
"""
Starts an execution, given an application description. Takes a JSON object.
:return: the new execution_id
"""
uid, role = get_auth(self)
......
......@@ -17,6 +17,7 @@
import base64
import logging
import functools
import tornado.web
......@@ -37,6 +38,7 @@ def catch_exceptions(func):
:param func:
:return:
"""
@functools.wraps(func)
def func_wrapper(*args, **kwargs):
"""The actual decorator."""
self = args[0]
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment