What is Akara

Akara is a framework for hosting, managing and coordinating services on the Web. Here are the most important concepts in Akara:

• service implementation::Python function (callable, generally) instrumented (usually with a decorator) to be exposed to the Web by Akara mount point::hierarchical path to a service from the Akara server root discovery document::listing of all the services running on an instance service ID::URI identifying the service behavior. So for example a particular XSLT transform service that behaves a certain way might be made available at multiple

Akara injects some globals into a module for use by service implementations.

AKARA_MODULE_CONFIG::a mapping of local settings from the config file, set upon module initialization WSGI_ENVIRON::the WSGI environment mapping for the current request

Module scope of Akara modules is not defined outside a service invocation. Avoid doing anything fancy such as spawning threads from service implementations unless you know what you're doing. One of the things you need to know to do is to copy any needed module globals injected by Akara's middleware.

Determining the mount point

If Akara has no other way to determine the mount point for a service implementation, it will use the function name. You can also specify a default mount point when you declare the function to be service implementation (i.e. through the decorator). Finally, you can override the mount point in the config file, using the form:

<functionname> = <mount-point>

Akara startup behavior

Modules are loaded in lexical order, and added to the service mapping (from mount point to service implementation). Akara dispatches to service implementations in order of the service mappings.

Registering services

There are several ways to prepare a service for deployment under Akara. The most basic mechanism is the simple_service decorator, applied to the callable which provides the implementation.

The query_template argument specifies the most specific portion of the URL template for invocations of the service parameter. The entire template is formed through simple string concatenation of: ServerPath + mount_point + query_template.

If you've designed the service to set parameters through URL query arguments, then query_template must start with ?. If parameters are set in the URL path hierarchy then query_template must start with /.

If query_template is not given, and all the following are true:

# the service request method is a GET # the service implementation callable does not take kwargs nor varargs # the service does not permit mutivalued query parameters (e.g. ?a=1&a=2)

then Akara will inspect the function parameters to build the query_template.

Services discovery

Akara is designed to make it easy to find and share services. There are many mechanisms for service discovery, of which the most general is probably the discovery document, accessible by GETting the root URL of any Akara instance

curl http://localhost:8880/

Looking up services using the API

...Registry of external services, mapped from service id to OpenSearch? template.

akara.registry.get_service_url(ident, **kwargs) to get the service URL given the service identifier and its kwargs. This will get the template from the local service with that identifer (if it exists), otherwise it gets it from the registry of external services.

also an akara.registry.get_internal_service_url(ident, **kwargs).

Remote peer Akara services

Akara is designed to work in peering systems, where one Akara server fairly transparently works with services mounted on a remote Akara instance.

The first matter to consider for each peer Akara server is "how am I invoked externally?" It might seem straightforward: if you set up Akara on myserver on port 8880, you might think "just assume it's http://localhost:8880 or http://myserver:8880", but in real world situations you may have to consider proxies and other intermediaries which might change this.

The administrator deploying Akara is best placed to figure this out, so Akara provides a means to configure the externally visible URL for the top-level of the Akara. Set the ServerPath value, which by default is "http://localhost:$port/". See also InternalServerPath, for the unusual cases when there is a different internal path to be used by one Akara service to another in the same Akara instance.

Pipelines

Warning. This section need to be updated to actual code as checked in

One of Akara's core features is the ability to coordinate the action of services. In general these are called pipelines.

There are some common classifications of pipelines.

• Synchronous pipeline -- Usually the pipeline is a series of transforms which are all invoked in order to satisfy the request:

request ---> service1 ---> service2 ---> response

• Trigger - when the Web response triggers another action is not required for completion fo the original response. In effect the other action is asynchronous. You can think of this as a tee.

request ---> service1 ---> response
                |
                |
                |
                v
             service2

Specifying pipelines:

• You can specify a synchronous pipeline in config, through input headers or output headers.
  • Configuration: you specify a service (the succeeding) to operate on the output of another service (the preceding)
  • Input headers: the user's request can specify in the request headers a sequence of succeeding service to operate on the input of the preceding service
  • Input headers: the preceding service can add in the response headers a sequence of succeeding service to operate on the response

request ---> service1 ---> service2 ---> service3 ---> response

• service1 is the preceding for service2 and service3. service1 is the immediately preceding for service2.

Registering a simple pipeline stage:

@simple_pipeline_stage(service_id, listen_for=[preceding_id1, preceding_id1]) #the listen_for list is an an or of the list items
func(environ, body):
    return response_obj #includes headers & new body