####
REST
####


****
NAME
****


Kernel::GenericInterface::Transport::HTTP::REST - GenericInterface network transport interface for HTTP::REST


****************
PUBLIC INTERFACE
****************


new()
=====


usually, you want to create an instance of this
by using Kernel::GenericInterface::Transport->new();


ProviderProcessRequest()
========================


Process an incoming web service request. This function has to read the request data
from from the web server process.

Based on the request the Operation to be used is determined.

No out-bound communication is done here, except from continue requests.

In case of an error, the resulting http error code and message are remembered for the response.


.. code-block:: perl

     my $Result = $TransportObject->ProviderProcessRequest();
 
     $Result = {
         Success      => 1,                  # 0 or 1
         ErrorMessage => '',                 # in case of error
         Operation    => 'DesiredOperation', # name of the operation to perform
         Data         => {                   # data payload of request
             ...
         },
     };



ProviderGenerateResponse()
==========================


Generates response for an incoming web service request.

In case of an error, error code and message are taken from environment
(previously set on request processing).

The HTTP code is set accordingly
- \ ``200``\  for (syntactically) correct messages
- \ ``4xx``\  for http errors
- \ ``500``\  for content syntax errors


.. code-block:: perl

     my $Result = $TransportObject->ProviderGenerateResponse(
         Success => 1,
         Data    => { # data payload for response, optional
             ...
         },
     );
 
     $Result = {
         Success      => 1,   # 0 or 1
         ErrorMessage => '',  # in case of error
     };



RequesterPerformRequest()
=========================


Prepare data payload as XML structure, generate an outgoing web service request,
receive the response and return its data.


.. code-block:: perl

     my $Result = $TransportObject->RequesterPerformRequest(
         Operation => 'remote_op', # name of remote operation to perform
         Data      => {            # data payload for request
             ...
         },
     );
 
     $Result = {
         Success      => 1,        # 0 or 1
         ErrorMessage => '',       # in case of error
         Data         => {
             ...
         },
     };



_Output()
=========


Generate http response for provider and send it back to remote system.
Environment variables are checked for potential error messages.
Returns structure to be passed to provider.


.. code-block:: perl

     my $Result = $TransportObject->_Output(
         HTTPCode => 200,           # http code to be returned, optional
         Content  => 'response',    # message content, XML response on normal execution
     );
 
     $Result = {
         Success      => 0,
         ErrorMessage => 'Message', # error message from given summary
     };



_Error()
========


Take error parameters from request processing.
Error message is written to debugger, written to environment for response.
Error is generated to be passed to provider/requester.


.. code-block:: perl

     my $Result = $TransportObject->_Error(
         Summary   => 'Message',    # error message
         HTTPError => 500,          # http error code, optional
     );
 
     $Result = {
         Success      => 0,
         ErrorMessage => 'Message', # error message from given summary
     };



_FlattenDataStructure()
=======================



.. code-block:: perl

     Returns a flattened hash/array of a given hash/array.
 
     $TransportObject->_FlattenDataStructure(
         Data => \%OldHash,
         Flattened => \%NewHash,
     );
 
     my %OldHash = (
         Config => {
             A => 1,
             B => 2,
             C => 3,
             D => [
                 2, 5, 6,
             ],
         },
         Config2 => 1
     );
 
     my %NewHash = (
         Config.A   => 1,
         Config.B   => 1,
         Config.C   => 1,
         Config.D.0 => 2,
         Config.D.1 => 5,
         Config.D.2 => 6,
         Config2    => 1,
     );