The output section is optional. You can use it to specify returning the results in multiple ways.
If omitted, the result of the resource will be returned in the result.
If no output section is defined in the resource, the result is automatically returned in the resource call result.
If an output section is defined, the result will be only processed by the elements in the output section.
If the output section is defined and you want to return the result in the response as well as by an output processor, add an element to the output section with the value result
.
If the output section is defined and there is no result
element, then the result of the remote output processors will be returned (true
or an error response).
An example output
section can look like this:
output:
-
result
-
processor: xml_remote
id: example XML Remote output
filename: example.xml
transport: ApiOpenStudio\Plugins\TransportSftp
parameters:
host: 192.168.1.13
username: example
root_path: /mnt/folder/
password: secret
port: 9022
timeout: 60
max_tries: 3
The first element in the output
section will cast the result to whatever is in the request Accept
header and return the result in the API call response.
The second element in the output
section uses the xml_remote
output processor: the output will be cast to json, and then uploaded to a remote location, using the defined transpoart (in this case: TransportSftp
) to transfer the file to the server/location specified in the parameters
section.
Returning the result in a resource call is the default, and is dynamically cast to the preferred format (i.e. XML, JSON, text, etc) by the resource caller's Accept
header.
If you inspect the code, in includes/Output/
, you will see the following files:
_
#text
.These do not need to be specified in the resource. They are dynamically called, depending on the Accept
header of the API call and will attempt to cast the result data to the requested format.
In addition to returning the result in the response, you can also upload the result to remote servers or generate an email from the data:
In addition to casting the results to different types and uploading the remote servers, ApiOpenStudio allows you to specify different transport methods. These are not included in the core, because that would cause too many, potentially redundant downloads and server dependencies.
Each transport has its own PHP module and server requirements, however they can be easily installed from composer, and then defined in the transport
section in the resource definition (Note: the value for transport
must be the full namespaced string):
Upload to a remote server using the FTP protocol.
$ composer require apiopenstudio/transport_ftp
Namespace:
ApiOpenStudio\Plugins\TransportAzureFtp
Upload to a remote server using the SFTP protocol.
$ composer require apiopenstudio/transport_sftp
Namespace:
ApiOpenStudio\Plugins\TransportSftp
Upload to an AWS S3 bucket.
$ composer require apiopenstudio/transport_s3
Namespace:
ApiOpenStudio\Plugins\TransportS3
Upload to a google cloud bucket.
$ composer require apiopenstudio/transport_google_cloud
Namespace:
ApiOpenStudio\Plugins\TransportGoogleCloud
Upload to an Azure Blob.
$ composer require apiopenstudio/transport_azure_blob
Namespace:
ApiOpenStudio\Plugins\TransportAzureBlob