ePages 7.48.0 - DE_EPAGES/WebService/API/Resource/BaseResource.pm

Package DE_EPAGES::WebService::API::Resource::BaseResource

Base class for REST resources.

Functions

chooseAction
chooseVariant
codecByContentType
href
match
new
params
producedContentTypes
requestCodec
requestContext

chooseAction

Uses HTTP content negotiation to find the appropriate content variant and the corresponding implementation. Throws a NotAcceptable error if the request cannot be served.

Syntax
($ActionName, $ResponseCodec) = $Resource->chooseAction($Request);
Input
$Request (HTTP::Request)
request object
Return
$ActionName (string)
action name from the $aVariants list in producedContentTypes
$ResponseCodec (object)
response encoder

chooseVariant

Uses HTTP content negotiation to find the appropriate content variant and the corresponding implementation. Throws a NotAcceptable error if the request cannot be served.

Syntax
$aVariant = $Resource->chooseVariant($Request);
Input
$Request (HTTP::Request)
request object
Return
(the selected variant of the $aVariants list in
producedContentTypes)
$aVariant

codecByContentType

Returns a suitable decoder/encoder object for a message with the given Content-Type. Returns undefined if there is no suitable codec.

Syntax
$Codec = $Resource->codecByContentType($ContentType);
Example
if ($RequestCodec) {
    $Data = $RequestCodec->decode($Request);
}
Input
$ContentType (string)
value of the Content-Type header
Return
$Codec (object)
content encoder/decoder

href

build an reference link based on API url and ressource related parameters

Syntax
$href = $Package->href($APIBaseURL, @Params);
Example
{
    rel => 'variations',
    href => DE_EPAGES::Product::API::Resource::ProductVariation->href($APIBaseURL, $SuperProduct->guid),
}
Input
$APIBaseURL (string)
rbase API url
@Params (array of string)
resource related parameters
Return
$href (string)
href of ressource

match

Tests if the resource can handle the request. If no, returns an empty list. If yes, returns a defined value. In some cases this value can be interpreted as object identifier for the actual resource.

Syntax
$Match = $Resource->match($Request);
Example
$Match = $Resource->match($Request);
if (defined $Match) {
    my $hRequestContext = $Resource->requestContext($Site, $Match, $Request);
}
Input
$Request (HTTP::Request)
request object
Return
$Match (string)
object identifier

new

Create a new REST resource object.

Syntax
$Resource = DE_EPAGES::WebService::API::Resource::BaseResource->new(%Options);
Input
%Options (hash)
(optional) options, currently not used
Return
$Resource (DE_EPAGES::WebService::API::Resource::BaseResource)
resource object

params

Returns the parameters for the action function.

Syntax
$hRequestContext = $Resource->params($ActionName, $Match, $Request);
Input
$ActionName (DE_EPAGES::Object::API::Object::Site)
name of the action
$Match (string)
result of match
$Request (HTTP::Request)
request object
Return
$hRequestContext (ref.hash)
request data with keys:
  • Object - business object - DE_EPAGES::Object::API::Object::Object
  • Action - action object or sub ref to handle the request - ref.code or DE_EPAGES::Permission::API::Object::Action
  • Params - parameters to the action function - ref.array
  • RequestCodec -
  • ResponseCodec -

producedContentTypes

Returns the available result content types of the resource for a given request method. Returns undefined if the method does not produce any content.

Syntax
$aVariants = $Resource->producedContentTypes( $RequestMethod );
Input
$RequestMethod (string)
request method, like 'GET' or 'POST'
Return
$aVariants (ref.array.array)
list of possible variants in order of precedence.
Each variant is an array with the following entries:
  • 0 - action or method name
  • 1 - content-type string

requestCodec

Returns a suitable decoder object to deserialze the request body. Returns undefined if the request does not have a Content-Type header or if there is no suitable decoder for the given Content-Type.

Syntax
$RequestCodec = $Resource->requestCodec($Request);
Example
if ($RequestCodec) {
    $Data = $RequestCodec->decode($Request);
}
Input
$Request (HTTP::Request)
request object
Return
$RequestCodec (object)
content encoder/decoder

requestContext

Tests if the resource can handle the request. If no, returns an empty list. If yes, returns the function to execute the request.

Syntax
$hRequestContext = $Resource->requestContext($Site, $Match, $Request);
Input
$Site (DE_EPAGES::Object::API::Object::Site)
site object
$Match (string)
result of match
$Request (HTTP::Request)
request object
Return
$hRequestContext (ref.hash)
request data with keys:
  • Object - business object - DE_EPAGES::Object::API::Object::Object
  • Action - action object or sub ref to handle the request - ref.code or DE_EPAGES::Permission::API::Object::Action
  • Params - parameters to the action function - ref.array
  • RequestCodec -
  • ResponseCodec -