provide( $method, $route, %opts )

• description

  A short description of the method and what it does.

• params

  A hash-ref of parameters in the syntax of Brannigan (see Brannigan::Validations for a complete references).

• cb

  An anonymous subroutine (or a subroutine reference) to run when the route is called. The method will receive the root topic class (or object, if the topics are written in object oriented style), and a hash-ref of parameters.

get( $route, %opts )

post( $route, %opts )

put( $route, %opts )

del( $route, %opts )

pre_route( $cb->( $self, $meth_and_route, \%params ) )

post_route( $cb->( $self, $meth_and_route, \$ret ) )

call( @args )

forward( $namespace, [ \%params ] )

$namespace is the method and route to execute, in the format "<METHOD>:<ROUTE>", where "METHOD" is one of "GET", "POST", "PUT", "DELETE", and "ROUTE" starts with a forward slash.

is_root( )

ANATOMY OF AN API

The main idea of a "McBain" API is this: a client requests the execution of a method provided by the API, sending a hash of parameters. The API then executes the method with the client's parameters, and produces a response. Every runner module will enforce a different response format (and even request format). When the API is used directly, for example, whatever the API produces is returned as is. The PSGI and Gearman::XS runners, however, are both JSON-in JSON-out interfaces.

A "McBain" API is built of one or more topics, in a hierarchical structure. A topic is a class that provides methods that are categorically similar. For example, an API might have a topic called "math" that provides math-related methods such as add, multiply, divide, etc.

Since topics are hierarchical, every API will have a root topic, which may have zero or more child topics. The root topic is where your API begins, and it's your decision how to utilize it. If your API is short and simple, with methods that cannot be categorized into different topics, then the entire API can live within the root topic itself, with no child topics at all. If, however, you're building a larger API, then the root topic might be empty, or it can provide general-purpose methods that do not particularly fit in a specific topic, for example maybe a status method that returns the status of the service, or an authentication method.

The name of a topic is calculated from the name of the package itself. The root topic is always called "/" (forward slash), and its child topics are named like their package names, in lowercase, relative to the root topic, with "/" as a separator instead of Perl's "::", and starting with a slash. For example, lets look at the following API packages:

        +------------------------+-------------------+------------------+
        | Package Name           | Topic Name        | Description      |
        +========================+===================+==================+
        | MyAPI                  | "/"               | the root topic   |
        | MyAPI::Math            | "/math"           | a child topic    |
        | MyAPI::Math::Constants | "/math/constants" | a child-of-child |
        | MyAPI::Strings         | "/strings"        | a child topic    |
        +------------------------+--------------------------------------+

You will notice that the naming of the topics is similar to paths in HTTP URIs. This is by design, since I wrote "McBain" mostly for writing web applications (with the PSGI runner), and the RESTful architecture fits well with APIs whether they are HTTP-based or not.

CREATING TOPICS

        use McBain;

This will import "McBain" functions into the package, register the package as a topic (possibly the root topic), and attempt to load all child topics, if there are any. For convenience, "McBain" will also import strict and warnings for you.

Notice that using "McBain" doesn't make your package an OO class. If you want your API to be object oriented, you are free to form your classes however you want, for example with Moo or Moose:

        package MyAPI;

        use McBain;
        use Moo;

        has 'some_attr' => ( is => 'ro' );

        1;

CREATING ROUTES AND METHODS

Route names are like topic names. They begin with a slash, and every topic can have a root route which is just called "/". Every method defined on a route will have a complete name (or path, if you will), in the format "<METHOD_NAME>:<TOPIC_NAME><ROUTE_NAME>". For example, let's say we have a topic called "/math", and this topic has a route called "/divide", with one "GET" method defined on this route. The complete name (or path) of this method will be "GET:/math/divide".

By using this structure and semantics, it is easy to create CRUD interfaces. Lets say your API has a topic called "/articles", that deals with articles in your blog. Every article has an integer ID. The "/articles" topic can have the following routes and methods:

        +------------------------+--------------------------------------+
        | Namespace              | Description                          |
        +========================+======================================+
        | POST:/articles/        | Create a new article (root route /)  |
        | GET:/articles/(\d+)    | Read an article                      |
        | PUT:/articles/(\d+)    | Update an article                    |
        | DELETE:/articles/(\d+) | Delete an article                    |
        +------------------------+--------------------------------------+

Methods are defined using the get(), post(), put() and del() subroutines. The syntax is similar to Moose's antlers:

        get '/multiply' => (
                description => 'Multiplies two integers',
                params => {
                        a => { required => 1, integer => 1 },
                        b => { required => 1, integer => 1 }
                },
                cb => sub {
                        my ($api, $params) = @_;

                        return $params->{a} * $params->{b};
                }
        );

Of the three keys above ("description", "params" and "cb"), only "cb" is required. It takes the actual subroutine to execute when the method is called. The subroutine will get two arguments: first, the root topic (either its package name, or its object, if you're creating an object oriented API), and a hash-ref of parameters provided to the method (if any).

You can provide "McBain" with a short "description" of the method, so that "McBain" can use it when documenting the API with mcbain2pod.

You can also tell "McBain" which parameters your method takes. The "params" key will take a hash-ref of parameters, in the format defined by Brannigan (see Brannigan::Validations for a complete references). These will be both enforced and documented.

As you may have noticed in the "/articles" example, routes can be defined using regular expressions. This is useful for creating proper RESTful URLs:

        # in topic /articles

        get '/(\d+)' => (
                description => 'Returns an article by its integer ID',
                cb => sub {
                        my ($api, $params, $id) = @_;

                        return $api->db->get_article($id);
                }
        );

If the regular expression contains captures, and a call to the API matches the regular expressions, the values captured will be passed to the method, after the parameters hash-ref (even if the method does not define parameters, in which case the parameters hash-ref will be empty - this may change in the future).

It is worth understanding how "McBain" builds the regular expression. In the above example, the topic is "/articles", and the route is "/(\d+)". Internally, the generated regular expression will be "^/articles/(\d+)$". Notice how the topic and route are concatenated, and how the "^" and "$" metacharacters are added to the beginning and end of the regex, respectively. This means it is impossible to create partial regexes, which only pose problems in my experience.

OPTIONS REQUESTS

For example, let's look at the following route:

        get '/something' => (
                description => 'Gets something',
                cb => sub { }
        );

        put '/something' => (
                description => 'Updates something',
                params => { new_content => { required => 1 } },
                cb => sub { }
        );

Calling "OPTIONS:/something" will return:

        {
                GET => {
                        description => "Gets something"
                },
                PUT => {
                        description => "Updates something",
                        params => {
                                new_content => { required => 1 }
                        }
                }
        }

CALLING METHODS FROM WITHIN METHODS

        get '/factorial => (
                description => 'Calculates the factorial of a number',
                params => {
                        num => { required => 1, integer => 1 }
                },
                cb => sub {
                        my ($api, $params) = @_;

                        if ($params->{num} <= 1) {
                                return 1;
                        } else {
                                return $api->forward('GET:/multiply', {
                                        one => $params->{num},
                                        two => $api->forward('GET:/factorial', { num => $params->{num} - 1 })
                                });
                        }
                }
        );

In the above example, notice how the "GET:/factorial" method calls both "GET:/multiply" and itself.

EXCEPTIONS

• "code" - An HTTP status code indicating the type of the error (for example 404 if the route doesn't exist, 405 if the route exists but the method is not allowed, 400 if parameters failed validation, etc.).
• "error" - The text/description of the error.

Depending on the type of the error, more keys might be added to the exception. For example, the parameters failed validation error will also include a "rejects" key holding Brannigan's standard rejects hash, describing which parameters failed validation.

When writing APIs, you are encouraged to return exceptions in this format to ensure proper handling by "McBain". If "McBain" encounters an exception that does not conform to this format, it will generate an exception with "code" 500 (indicating "Internal Server Error"), and the "error" key will hold the exception as is.

PRE-ROUTES AND POST-ROUTES

Every topic in your API can define pre and post routes. The pre route is called right before a route is executed, while the post route is called immediately after.

You should note that the pre and post routes are called on every route execution (when applicable), even when forwarding from one route to another.

Pre and post routes are hierarchical. When a route is executed, "McBain" will analyze the entire chain of topics leading up to that route, and execute all pre and post routes on the way (if any, of course). So, for example, if the route "/math/factorial" is to be executed, "McBain" will look for pre and post routes and the root topic ("/"), the "/math" topic, and the "/math/factorial" topic (if it exists). Whichever ones it finds will be executed, in order.

The "pre_route" subroutine gets as parameters the API package (or object, if writing object-oriented APIs, or the context object, if writing in contextual mode), the full route name (the method and the path, e.g. "POST:/math/factorial"), and the parameters hash-ref, after validation has occurred.

        package MyApi::Math;

        post '/factorial' => (
                ...
        );

        pre_route {
                my ($self, $meth_and_route, $params) = @_;

                # do something here
        }

The "post_route" subroutine gets the same parameters, except the parameters hash-ref, in which place a reference to the result returned by the actual route is passed. So, for example, if the "POST:/math/factorial" method returned 13, then "post_route" will get a reference to a scalar variable whose value is 13.

        post_route {
                my ($self, $meth_and_route, $ret) = @_;

                if ($$ret == 13) {
                        # change the result to 14, because
                        # 13 is an unlucky number
                        $$ret = 14;
                }
        }

CONTEXTUAL MODE

Contextual mode is an optional way of writing "McBain" APIs, reminiscent of web application frameworks such as Catalyst and Leyland. The main idea is that a context object is created for every request, and follows it during its entire life.

In regular mode, the API methods receive the class of the root package (or its object, if writing object oriented APIs), and a hash-ref of parameters. This is okay for simple APIs, but many APIs need more, like information about the user who sent the request.

In contextual mode, the context object can contain user information, methods for checking authorization (think role-based and ability-based authorization systems), database connections, and anything else your API might need in order to fulfill the request.

Writing APIs in contextual mode is basically the same as in regular mode, only you need to build a context class. Since "McBain" doesn't intrude on your OO system of choice, constructing the class is your responsibility, and you can use whatever you want (like Moo, Moose, Class::Accessor). "McBain" only requires your context class to implement a subroutine named "create_from_env( $runner, \%env, @args_to_call )". This method will receive the name of the runner module used, the standard environment hash-ref of "McBain" (which includes the keys "METHOD", "ROUTE" and "PAYLOAD"), plus all of the arguments that were sent to the "call( @args )" method. These are useful for certain runner modules, such as the PSGI runner, which gets the PSGI hash-ref, from which you can extract session data, user information, HTTP headers, etc. Note that this means that if you plan to use your API with different runner modules, your "create_from_env()" method should be able to parse differently formatted arguments.

Note that currently, the context class has to be named "__ROOT__::Context", where "__ROOT__" is the name of your API's root package. So, for example, if your API's root package is named "MyAPI", then "McBain" will expect "MyAPI::Context".

Note: since v2.1.0, if "McBain" doesn't find a package named "__ROOT__::Context", it will go up the package hierarchy until it finds one. For example, if the root package of your API is "Some::API", then McBain will try "Some::API::Context", then "Some::Context", then finally "Context". This was added to allow the sharing of the same context class in a project comprised of several APIs.

When writing in contextual mode, your API methods will receive the context object instead of the root package/object, and the parameters hash-ref.

Let's look at a simple example for writing APIs in contextual mode. Say our API is called "MyAPI". Let's begin with the context class, "MyAPI::Context":

        package MyAPI::Context;

        use Moo;
        use Plack::Request;

        has 'user_agent' => (
                is => 'ro',
                default => sub { 'none' }
        );

        sub create_from_env {
                my ($class, $runner, $mcbain_env, @call_args) = @_;

                my $user_agent;

                if ($runner eq 'McBain::WithPSGI') {
                        # extract user agent from the PSGI env,
                        # which will be the first item in @call_args
                        $user_agent = Plack::Request->new($call_args[0])->user_agent;
                }

                return $class->new(user_agent => $user_agent);
        }

        1;

Now let's look at the API itself:

        package MyAPI;

        use McBain -contextual;

        get '/' => (
                cb => sub {
                        my ($c, $params) = @_;

                        if ($c->user_agent =~ m/Android/) {
                                # do it this way
                        } else {
                                # do it that way
                        }

                        # you can still forward to other methods
                        $c->forward('GET:/something_else', \%other_params);
                }
        );

        1;

So as you can see, the only real change for API packages is the need to write "use McBain -contextual" instead of "use McBain". The only "challenge" is writing the context class.

init( $runner_class, $target_class )

You can do whatever initializations you need to do here, possibly manipulating the target class directly. You will probably only want to do this on the root topic, which is why "is_root( )" is available on $target_class.

You can look at "WithPSGI" and "WithGearmanXS" to see how they're using the "init()" method. For example, in "WithPSGI", Plack::Component is added to the @ISA array of the root topic, so that it turns into a Plack app. In "WithGearmanXS", the "init()" method is used to define a "work()" method on the root topic, so that your API can run as any standard Gearman worker.

generate_env( $runner_class, @call_args )

The hash-ref returned must have the following key-value pairs:

• ROUTE - The route to execute (string).
• METHOD - The method to call on the route (string).
• PAYLOAD - A hash-ref of parameters to provide for the method. If no parameters are provided, an empty hash-ref should be given.

The returned hash-ref is called $env, inspired by PSGI.

generate_res( $runner_class, \%env, $result )

handle_exception( $runner_class, $error, @args )

The method should format the error before returning it to the user, similar to what "generate_res()" above performs, but it allows you to handle exceptions gracefully.

Whatever arguments were provided to "call()" will be provided to this method as-is, so that you can inspect or use them if need be. "WithGearmanXS", for example, will get the Gearman::XS::Job object and call the "send_fail()" method on it, to properly indicate the job failed.