Net::API::REST::Endpoint - Endpoint object for Net::APi::REST
my $ep = Net::API::REST::Endpoint->new( handler => $code_ref, # could be also restricted. access => 'public', methods => [qw( GET POST )], path_info => '/some/extra/path', variables => { person_id => 123 }, params => { some_data => $some_value }, );
Then, in the method mapped to the endpoint called from Net::API::REST::handler():
my $self = shift( @_ ); my $ep = $self->endpoint; my $vars = $ep->variables; # For example /users/123/name and assuming an endpoint map with _vars => { _name => user_id } # my $user_id = $vars->{user_id};
The route could look something like the following:
$self->{routes} = { # API version 1 1 => { # special case ? '.well-known' => $self->curry::well_known, # This inherits the public access csrf_check => $self->curry::csrf_check, users => { # Nope, cannot stop there, sends back noop _handler => $self->curry::noop, # From now on, all endpoints below will be restricted _access_control => 'restricted', # For example: https://api.example.com/users/123 _var => { _name => 'user_id', # Return the user information _handler => $self->curry::user_info, # This is a read-only endpoint, query string will be discarded and no POST or PUT allowed _allowed_methods => [qw( GET )], # discretionary hash of key-value pairs _params => { some_data => $some_value }, # https://api.example.com/users/123/first_name first_name => { _handler => $self->curry::user_first_name, _allowed_methods => [qw( GET POST )], }, payment_method => { # Create, Retrieve, Update, Delete _allowed_methods => [qw( PUT GET POST DELETE )], _var => { _handler => $self->curry::user_pm, _name => 'pm_id', }, }, # etc... }, }, }, # api version 2, etc. # 2 => {}, };
As you can see endpoints below https://api.example.com/users would be restricted, which would mean that your api would check the value provided "access" and check for user credentials before granting execution of the query.
https://api.example.com/users
Note that the api version number is not necessarily part of the path, although it could.
It can also be provided in the Accept header. See "accept" in Net::API::REST::Request for more details.
For example:
https://api.example.com/v1/users/123/payment_method/456 https://api.example.com/v1.2/users/123/payment_method/456 https://api.example.com/1/users/123/payment_method/456 https://api.example.com/users/123/payment_method/456
with an http Accept field value of: application/json; charset=utf-8; version=1
If no api version is specified either way, then the latest one provided by "api_version" in Net::API::REST is used.
See "api_version" in Net::API::REST for more details.
Sets or gets the accessibility of the endpoint, such as public, or restricted or anything else you want to use.
public
restricted
The access level you set has a cascading effect on all the endpoints below itself as shown in the example in the "SYNOPSIS" above.
This defaults to public.
Set or gets the code reference that is called for a given endpoint.
For example, if you have an endpoint route defined as:
{ version => $self->curry::version, }
Then the "handler" will be a code reference to version.
version
For handler, curry is very handy and much better than to write a bunch of anonymous routines like:
{ _handler => sub{ $self->user_pm( @_ ) }, }
Provided with an HTTP method name, such as POST or GET, and this will return true, if this method is allowed for this endpoint, or false otherwise.
POST
GET
Sets or gets the array reference of allowed methods for this endpoint. For example GET, POST, PUT, DELETE
PUT
DELETE
Sets or gets a discretionary hash reference of key-value pairs to be accessed and used in your code.
The path URI for this endpoint. This sets or gets an URI object.
Sets or gets possible path info specified when the user made the api call.
For example, assuming an endpoint /create/file, and user calling /create/file/some/where/file.txt, then /some/where/file.txt would be set as path info assuming there is nothing below the endpoint /create/file declared in the api route, otherwise, of course, this would trigger a 404 Not found error.
/create/file
/create/file/some/where/file.txt
/some/where/file.txt
404 Not found
Sets or gets the hash reference containing the variables and their values.
For example, assuming and endpoint call like /users/123/last_name, then the route hash reference would look like:
/users/123/last_name
{ users => { _handler => $self->curry::users, _var => { _handler => $self->curry::users, _name => 'user_id', first_name => $self->curry::user_first_name, last_name => $self->curry::user_last_name, } } }
Then, "route" in Net::API::REST would set the variable user_id to 123.
user_id
123
If a same variable is declared and found twice in the path, it is automatically switched to an array reference. Thus, if the value of a given variable is an array reference, you know instantly there was more than one value provided in the query.
You can always get the query string, if any, by using "params" in Net::API::REST::Request:
my $self = shift( @_ ); # $q is not an hash reference my $q = $self->request->params; # or maybe the user sent you a json payload? $q = $self->request->payload if( !scalar( keys( %$q ) ) && $self->request->payload );
Jacques Deguest <jack@deguest.jp>
Net::API::REST, Net::API::REST::Request, Net::API::REST::Response, Net::API::REST::Query
Copyright (c) 2018-2023 DEGUEST Pte. Ltd.
You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.
To install Net::API::REST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::API::REST
CPAN shell
perl -MCPAN -e shell install Net::API::REST
For more information on module installation, please visit the detailed CPAN module installation guide.