NAME API::McBain - Framework for building auto-validating, self-documenting APIs. VERSION version 0.1 SYNOPSIS HOW YOU WRITE YOUR API package MyAPI; use API::McBain # also imports warnings and strict separator => '.'; # that is the default, you can drop this or use something else 1; package MyAPI::Math; use API::McBain::Topic # also imports warnings and strict topic => 'math'; # if you don't provide one, McBain will use a lowercased version # of the end of the package name (in this case, 'math'). provide('add') ->description('Receives two integers, returns their sum.') ->param(one => { integer => 1, required => 1 }) ->param(two => { integer => 1, required => 1 }) ->returns('integer') ->callback(sub { my ($self, %params) = @_; return $params{one} + $params{two}; }); HOW YOU/OTHERS USE YOUR API: use MyAPI; my $api = MyAPI->new; print $api->call('math.add', one => 1, two => 4); # prints 5 print $api->call('math.add', one => 1); # throws exception HOW YOU/OTHERS LEARN YOUR API: # echoing this in the command line: $ mcbain describe MyAPI::Math # will result in the following output: > MyAPI::Math > > Provided methods: > * add > Description: Receives two integers, returns their sum. > Parameters: > one: required, integer > two: required, integer > Return type: integer DESCRIPTION WARNING: this is an early release. API is subject to change, bugs may lurk under your bed. "McBain" is a simple framework for building APIs in Perl. It takes the burden of validating parameters so you don't need to repeat yourself with endless sanity checks; helps ensuring your APIs are written in a consistent manner; and also makes documenting them easier, making that process at least semi-automatic. While Perl subroutines being endlessly flexible is one of the language's main strengths, there are some cases where finer grained control over them could be welcome. APIs that are meant to be used by others (say, an API for a web service you created meant to be used by customers) are one such example. You need to make sure that users of your code use it and don't abuse it. You need to express your API methods' requirements explicitly, and validate input in such a way that bad input does not cause problems, and users can understand what they did wrong. This is just two things your API needs to do, but doing them is hard, boring and tedious. While helpers like subroutine signatures are available, they are not flexible enough and are far from actually helping to solve the problem. "McBain" provides you with a simple syntax for building such methods and documenting them. It uses Brannigan to validate input according to your specifications, and also provides a command line tool, mcbain, that provides a "man"-like interface for reading your API's documentation, while automatically parsing input specifications for each method so you don't need to document input requirements yourself. In "McBain", your API methods are categorized into "topics". Each topic is a Perl package that uses API::McBain::Topic. It has a name, and as many "provided methods" as you want. Each method also has a name, of course, and users can call these methods by referring to their complete name, including the topic. For example, if topic "math" has a method called "subtract", users call "math.subtract" to invoke that method (the dot character "." is the default separator between topic and method names, but can be modified to anything you want). Your API will always start with a top level package that uses this module ("API::McBain"). The top level package is not a topic and cannot provide methods. "McBain" is built to be as lightweight as possible. It does not rely on "Moose" or any other OO modules, and I plan to keep dependencies to a minimum. DIAGNOSTICS "McBain" throws exceptions of "McBain"-specific classes that extend Exception::Class::Base. The following exception classes currently exist: * "API::McBain::Exception::NotFound" - Thrown when a call is made to a topic and/or method that does not exist. Possible error strings are "Topic %s does not exist" and "Topic %s does not provide a method named %s". * "API::McBain::Exception::BadRequest" - Thrown when a call is made with an illegal namespace (so McBain cannot calculate topic and method, probably due to wrong or missing separator), in which case "Illegal namespace %s" will be the error text; or because input parameters for a provided method failed validation, in which case "Parameters failed validation" will be the error text, and the exception object will also have a field named "rejects" with Brannigan's standard "_rejects" structure (see Brannigan for more info). CONFIGURATION AND ENVIRONMENT "API::McBain" requires no configuration files or environment variables. DEPENDENCIES "API::McBain" depends on the following CPAN modules: * Brannigan * Carp * Exception::Class * Module::Pluggable * Tie::IxHash * Try::Tiny The command line utility, mcbain, depends on the following CPAN modules: * Getopt::Compact::WithCmd * Module::Load * Term::ANSIColor INCOMPATIBILITIES WITH OTHER MODULES None reported. BUGS AND LIMITATIONS No bugs have been reported. Please report any bugs or feature requests to "bug-API-McBain@rt.cpan.org", or through the web interface at . SUPPORT You can find documentation for this module with the perldoc command. perldoc API::McBain You can also look for information at: * RT: CPAN's request tracker * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN AUTHOR Ido Perlmuter LICENSE AND COPYRIGHT Copyright (c) 2013, Ido Perlmuter "ido@ido50.net". This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either version 5.8.1 or any later version. See perlartistic and perlgpl. The full text of the license can be found in the LICENSE file included with this module. DISCLAIMER OF WARRANTY BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.