Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Server::API2UsersContributed PeOpenXPKI::Server::API2::EasyPlugin(3)

NAME
       OpenXPKI::Server::API2::EasyPlugin - Define an OpenXPKI API plugin

DESCRIPTION
       To define a new API plugin simply say:

	   package OpenXPKI::Server::API2::Plugin::MyTopic::MyActions;
	   use OpenXPKI::Server::API2::EasyPlugin;

	   command "aaa" => {
	       # parameters
	   } =>	sub {
	       # actions
	       ...
	       $self->api->another_command();
	       ...
	   };

       This will modify	your package as	follows:

       o   imports "Moose" (i.e. adds "use Moose;" so you don't	have to	do it)

       o   provides the	"command" keyword (just	an imported sub	really)	to
	   define API commands

       o   applies the Moose role OpenXPKI::Server::API2::EasyPluginRole

       o   applies the Moose metaclass role (aka. "trait")
	   OpenXPKI::Server::API2::EasyPluginMetaClassTrait

       It currently does not seem to be	possible to set	a custom base class
       for your	plugin,	but you	can instead easily add another role to it:

	   package OpenXPKI::Server::API2::Plugin::MyTopic::MyActions;
	   use OpenXPKI::Server::API2::EasyPlugin;

	   with	"OpenXPKI::Server::API2::Plugin::MyTopic::Base";

KEYWORDS (imported functions)
       The following functions are imported into the package that uses
       "OpenXPKI::Server::API2::EasyPlugin".

   command
       Define an API command including input parameter types.

       Example:

	   command "givetheparams" => {
	       name => { isa =>	'Str', matching	=> qr/^(?!Donald).*/, required => 1 },
	       size => { isa =>	'Int', matching	=> sub { $_ > 0	} },
	   } =>	sub {
	       my ($self, $po) = @_;

	       $po->name("The genious ".$po->name) if $po->has_name;

	       if ($po->has_size) {
		   $self->some_helper($po->size);
		   $po->clear_size; # unset the	attribute
	       }

	       $self->process($po);
	   };

       Note that this can be written as	(except	for the	dots obviously)

	   command(
	       "givetheparams",
	       {
		   name	=> ...
		   size	=> ...
	       },
	       sub {
		   my ($self, $po) = @_;
		   return { ...	};
	       }
	   );

       You can access the API via "$self->api" to call another command.

       Parameters

       o   $command_name - name	of the API command

       o   $params - HashRef containing	the parameter specifications. Keys are
	   the parameter names and values are HashRefs with options.

	   Allows the same options as Moose's has keyword (i.e.	isa, required
	   etc.)  plus the following ones:

	   o   "matching" - Regexp or CodeRef that matches if TRUE value is
	       returned.

	   You can use all Moose types (Str, Int etc) plus OpenXPKI's own
	   types defined in OpenXPKI::Server::API2::Types
	   ("OpenXPKI::Server::API2" automatically imports them).

       o   $function - CodeRef with the	command	implementation.	On invocation
	   it gets passed two parameters:

	   o   $self - the instance of the command class (that called "api").

	   o   $po - a parameter data object with Moose	attributes that	follow
	       the specifications in $params above.

	       For each	attribute two additional methods are available on the
	       $po: A clearer named "clear_*" to clear the attribute and a
	       predicate "has_*" to test if it's set. See "Predicate and
	       clearer methods"	in Moose::Manual::Attributes if	you don't know
	       what that means.

perl v5.32.0			  2020-08OpenXPKI::Server::API2::EasyPlugin(3)

NAME | DESCRIPTION | KEYWORDS (imported functions)

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OpenXPKI::Server::API2::EasyPlugin&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help