Skip to main content

REST API / WebEditor

This documentation section provides details about the available RESTful routes, which can be accessed either through SQL commands or directly through a web browser. It also introduces the AOP Webeditor, a web-based tool designed for testing and debugging the AOP request JSON generated from the APEX application.

RESTful Routes​

AOP allows you to query some information about the environment using different routes. You can check the version of the application, supported template types, prepend and append files, and many more.

Invalid Route

If an invalid route or URL is specified, you will get an error message of 'Cannot GET / your_url '

The routes are mentioned below:

/

For AOP on-prem, This will return a web editor which you can use to quickly change the template/data of an existing JSON or simply use it to test and debug out AOP.

For AOP Cloud users, this will return the AOP Logo and version in plain HTML.

/marco​

This route is to verify the status and reachability of the AOP server. If the server is active, it will respond with a "polo" string and an HTTP 200 status code. You can use this route to check if the AOP server is running and accessible.

select apex_web_service.make_rest_request('http://localhost:8010/marco','GET') from dual;

/version​

This will return the current version of AOP.

select apex_web_service.make_rest_request('http://localhost:8010/version','GET') from dual;

/soffice​

select apex_web_service.make_rest_request('http://localhost:8010/soffice','GET') from dual;

/officetopdf​

This will return the current version of OfficeToPdf used. (Only available in Windows environment).

select apex_web_service.make_rest_request('http://localhost:8010/officetopdf','GET') from dual;

/supported_template_mimetypes​

This returns JSON data of the mime types of templates that AOP supports as shown below.

select apex_web_service.make_rest_request('http://localhost:8010/supported_template_mimetypes','GET') from dual;

/supported_output_mimetypes​

This returns the supported conversion for the given template extension. For example:

select apex_web_service.make_rest_request('http://localhost:8010/supported_output_mimetypes?template=docx','GET') from dual;

Specify the extension of the template as ?template=template_file_extension as shown below:

The above image shows that a docx file can be converted to docx, html, onepagepdf, pdf, rtf and txt.

Similary you can try with:

/supported_output_mimetypes?template=xlsx

/supported_output_mimetypes?template=pptx

/supported_output_mimetypes?template=pdf

note

You will get an empty JSON if the conversion type isn't supported.

/supported_prepend_mimetypes​

This returns the supported prepend file mime types in JSON format.

select apex_web_service.make_rest_request('http://localhost:8010/supported_prepend_mimetypes','GET') from dual;

/verify_template_hash​

This returns if the given hash is valid or not. i.e. it returns true and expiry time when the given hash is in the cache and returns false if not. The format of this endpoint is /verify_template_hash?hash={hashcode} where hashcode is hash of the cached template, for example:

http://localhost:8010/verify_template_hash?hash=faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d

select apex_web_service.make_rest_request('http://localhost:8010/verify_template_hash?hash=faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d','GET') from dual;

Output JSON:

{
    "valid": true,
    "status": "Hash is valid",
    "expiry_date_time": "12:47:27 GMT+0545 (Nepal Time) Fri Dec 17 2021",
    "expiry_time_remaining": "00h 53m 40s 0ms",
    "iso_expiry_date_time": "2021-12-17T07:02:27.719Z",
    "ms_expiry_time_remaining": 3220012,
    "hash": "faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d"
}

/renew_template_hash​

This will renew the hash expiry time for next 1 hour. If the hash is not valid, it will return an error message. The format of this endpoint is /renew_template_hash?hash={hashcode} where hashcode is hash of the cached template, for example:

select apex_web_service.make_rest_request('http://localhost:8010/renew_template_hash?hash=faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d','GET') from dual;

Output JSON:

{
    "status": "Successfully renewed hash",
    "valid": true,
    "hash": "faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d",
    "new_expiry_date_time": "12:54:23 GMT+0545 (Nepal Time) Fri Dec 17 2021",
    "iso_expiry_date_time": "2021-12-17T07:09:23.196Z"
}

/invalidate_template_hash​

This will invalidate the hash by deleting the given hash. If the hash is not valid, it will return an error message. The format of this endpoint is /invalidate_template_hash?hash={hashcode} where hashcode is hash of the cached template, for example:

select apex_web_service.make_rest_request('http://localhost:8010/invalidate_template_hash?hash=faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d','GET') from dual;

Output JSON:

{
    "valid": true,
    "status": "Invalidated the given template hash successfully.",
    "hash": "faebf702a671ca3c56872abd94cebaacf6eb3b2e0d570cf2f390a01c7b2f509d"
}

/ipp_check​

This returns the status of the ipp printer based on the given ipp_url and version. For example:

select apex_web_service.make_rest_request('http://localhost:8010/ipp_check?ipp_url=http://localhost:3000&version=1.1','GET') from dual;

Specify the ipp_url and version as ?ipp_url=ipp_printer_url&version=version as shown below.

ipp_check

/stats​

This returns the current statistics of the AOP server. The statistics are returned in JSON format and currently, it includes the total number of instances running and the queue details of the converter. For example: 

select apex_web_service.make_rest_request('http://localhost:8010/stats','GET') from dual;

Access_token​

Also, the access token can be specified (if required) in two ways:

  1. On the URL:

    It can be specified as ?access_token=your_access_token as shown below.

    http://localhost:8010/stats?access_token=*enter_your_access_token*

    For example: If the access token is abc123 then the above URL will be

    http://localhost:8010/stats?access_token=abc123

  2. On the header:

    It can be specified on the header while sending the request as access_token: your_access_token

/server_errors​

This displays the server errors of the AOP server. The server errors are returned in log file format and can be accessed as follow:

select apex_web_service.make_rest_request('http://localhost:8010/server_errors','GET') from dual;

Also, the access token can be specified (if required) in two ways as mentioned above in stats. The latest logs can be retrieved by using ?latest=number_of_lines. If the URL is http://localhost:8010/server_errors?latest=10 then the latest 10 lines (i.e. bottom 10 lines) of the log file will be returned.

Note: If the log file size is greater than 10MB, then it will get downloaded as a file.

/server_printjobs​

This displays the server printjob errors of the AOP server. The server printjobs errors are returned in a log file format of the current date and can be accessed as follow:

select apex_web_service.make_rest_request('http://localhost:8010/server_printjobs','GET') from dual;

Also, the access token can be specified (if required) by two ways as mentioned above in stats. Specific date can also be used as the date parameter in the format YYYYMMDD. Like for 27 December 2021 date can be specified as ?date=20211227

http://localhost:8010/server_printjobs?date=20210522

/network_logs​

This displays the network logs of the AOP server. The logs are returned in a log file format of the current date and can be accessed as follow:

select apex_web_service.make_rest_request('http://localhost:8010/network_logs','GET') from dual;

Also, the access token can be specified (if required) by two ways as mentioned above in stats. Specific date can also be used as the date parameter in the format YYYYMMDD. Like for 27 December 2021 date can be specified as ?date=20211227

/download​

A unique download link is generated by the AOP server (upon request) and this link can be used to download the file. Want AOP to generate a unique link for a file? Check this out: output_polling of output properties.

The format for this endpoint is /download/_unique_reference_id_

select apex_web_service.make_rest_request('http://localhost:8010/download/492a9badsd4g676dfg','GET') from dual;

Additional URL parameters that it supports are:

  • secretkey: secretkey is a string that is used to decrypt the file (the key which was used to encrypt the file). If the secret key wasn’t used to encrypt the file then this parameter can be ignored.
  • delete_after_download : delete_after_download is a boolean value(true or false). If it is set to true then, it deletes the file after downloading.

These can be specified as following, some examples:

http://localhost:8010/download/f5b685d0cea41a723b8951492a9ba64dfc1e65199641aa2ddb9d22a27d67641e?secretkey=AOPSecretKey http://localhost:8010/download/f5b685d0cea41a723b8951492a9ba64dfc1e65199641aa2ddb9d22a27d67641e?delete_after_download=true

Important Note

From AOPv24.1, You can get status of the async request(Processing, Successful, Not Found and Failed) using respone status code of the response.

Encrypted file on the server is deleted after 10 hours so, a valid url with valid secret key may result in an error message.

  1. Successful Response (200): The request is successful and will return a file.
  2. Request Not Completed (202): The request is still processing, and you will need to check back later. It returns a JSON with additional information.
  3. Request Not Found (404): The file you are looking for cannot be found. This could be because the file might have been deleted. Note: A file will be deleted if any of the following conditions are met:
    1. Your request is older than 10 hours.
    2. You have set the 'delete_after_download' parameter to true while downloading.
  4. Request Failed (500): An error occurred on the server while processing your request. It returns a JSON with more information about the error.

/requestoptionstatus​

You can create an asynchronous request that will process your file and send it to provided attributes while you perform other tasks. A unique URL is generated by the AOP server (upon request) and this link can be used to view the status of the asynchronous request made by a user. Check request_option to explore how you can use this feature.

The format for this endpoint is /requestoptionstatus/_unique_reference_id_

select apex_web_service.make_rest_request('http://localhost:8010/requestoptionstatus/794b82d0-2d0d-11ed-a18f-5763f46d487d','GET') from dual;

Note: You can check the status for 10 hours from the time of your request.

/checkconfiguration​

Available From: v22.2.5

This route allows the AOP server to verify the configuration of the system running AOP. It retrieves and displays information such as the AOP version, operating system details, permissions, converter information including version, JAVA version, officetopdf details, and the supported conversions based on the provided license. It takes some time to check and display the configuration information.

select apex_web_service.make_rest_request('http://localhost:8010/checkconfiguration','GET') from dual;

/available_fonts​

Available From: v22.2.6

This route allows the AOP server to return the installed fonts. It retrieves and display all the installed fonts which can be used in the AOP.

note

The fontNames are shown in the same fontStyle.

select apex_web_service.make_rest_request('http://localhost:8010/available_fonts','GET') from dual;

/get_requests_lists​

Available From: v23.1

This route provides a JSON response containing a list of requests that are either in the processing state or queued. The response includes information such as the unique URID, start time, JSON size, template name & type, output type, logging data, and the status of each request.

select apex_web_service.make_rest_request('http://localhost:8010/get_requests_lists','GET') from dual;

An example of the response is as shown below.

Access Token

If access token is added in the AOP configuration (aop_config.jsonc), it is necessary to include access token in the url or in header for the routes /get_requests_lists and /kill_worker. An example about including access token, visit Access Token.

/kill_worker​

Available From: v23.1

This route allows the termination or killing of active requests. For the termination process, providing the URID of the ongoing request is mandatory, which can be obtained using the /get_requests_lists route. 

select apex_web_service.make_rest_request('http://localhost:8010/kill_worker?urid=06743cc6-f539-433a-b71b-8f43a004024e','GET') from dual;

Following response is obtained including a file that has information about the termination and URID.

/get_aop_config​

Available From: v24.1

This route provides the aop configurations available in the aop_config.jsonc.

access_token

access_token is mandatory to use this route. If it hasn't been set in the aop_config.jsonc file, then first you need to manually configured access_token in aop_config.jsonc. Without this step, AOP will prevent the retrieval/update of configurations. 

select apex_web_service.make_rest_request('http://192.168.1.75:8010/get_aop_config?access_token=abcde','GET') from dual;

An example for this route request is as follow.

get aop config sc example

/update_config​

Available From: v24.1

This route allows the user to add/modify the aop_config parameters like configs, post_process_commands and converters parameters in the aop_config.jsonc file. You need to perform a POST request with a json body with an object aop_config.

access_token

access_token is mandatory to use this route. If it hasn't been set in the aop_config.jsonc file, then first you need to manually configured access_token in aop_config.jsonc. Without this step, AOP will prevent the retrieval/update of configurations. 

DECLARE
    l_json_body    VARCHAR2(4000);
    l_response     CLOB;
BEGIN
    l_json_body := '{"aop_config":{"config":{"request_timeout": 1000, "idle_timeout": 900},"post_process_commands":{"echo":"echo \"{inputFile} with input format ${inputFormat} has been successfully processed.\""}}}';
    apex_web_service.g_request_headers(1).name := 'Content-Type';
    apex_web_service.g_request_headers(1).value := 'application/json';
    apex_web_service.g_request_headers(2).name := 'access_token';
    apex_web_service.g_request_headers(2).value := 'abcde';

    l_response := apex_web_service.make_rest_request(
        p_url            => 'http://192.168.1.69:8010/update_config',
        p_http_method    => 'POST',
        p_body           => l_json_body
    );

    DBMS_OUTPUT.PUT_LINE('Response: ' || l_response);

EXCEPTION
    WHEN others THEN
        DBMS_OUTPUT.PUT_LINE('Error: ' || SQLERRM);
END;

update aop config sc example

AOP Webeditor​

The AOP On-Prem system is integrated with a Webeditor tool that enables users to test and debug the AOP request in the form of JSON. The Webeditor is a simple web interface that provides functionality for viewing and editing the debug JSON, allowing users to inspect, analyze and modify the debug JSON for troubleshooting purposes. It allows sending the request in the form of JSON to AOP Server and provides the output.

You can get the debug JSON by inserting the following PL/SQL code in the Init PL/SQL section of the dynamic action:

aop_api_pkg.g_debug:='Local';

Below are the important features and highlights of the Webeditor. Upon initial loading, the Webeditor displays a walkthrough that provides an introduction to the various sections and functionalities available within the tool. This walkthrough guides users through the different sections and highlights the capabilities of the Webeditor.

Main Sections​

AOP Webeditor compromises the three main sections.

  1. Editor
  2. Logging
  3. Utilities

You can toggle between the Editor and Logging sections by clicking on the Logging button at the top-right corner of the webeditor.

Editor​

As its name suggests, the Editor provides functionalities for viewing and editing the JSON. The image below highlights the key subsections within the Editor.

  1. JSON Drop Section : Users have the option to either drag and drop a debug JSON file or click to load it into the Webeditor.
  2. Composer Section : This section enables users to load files such as templates, subtemplates, append files, and prepend files.
  3. Output Process Section: In this section, users can modify the output type and specify the server URL. By clicking the "PROCESS" button, the loaded JSON request is sent to the AOP server for processing.
  4. File Cache : The Webeditor includes a file cache feature, which stores files for future use.
  5. Encode/Decoder : This functionality allows users to convert files to base64 encoded strings and vice versa. For example, users can drop an image file to obtain its corresponding base64 string. Similarly, they can provide a base64 string to decode it into a file.
  6. Logging : By clicking on this button, users can access the logging tab, where they can retrieve the request logs.
  7. Utility : This section provides various options such as IPP Check, Stats, Download, Template Hash Tools, Logs, Supported Type, and Version Check functionalities.

In the Composer section, the LOAD SAMPLE button provides the list of sample JSON for different output types, serving as a reference for users. The purpose of the CLEAR button is to remove the loaded JSON, including template, data and other files.

The different sections of Composer section to manipulate the files, data, and JSON are shown below.

The different tabs shown below are described below:

  1. Files/Template : This tab enables users to access, edit, and download the template, subtemplate, prepend, and append files.
  2. Data : This tab provides a region where users can drag and drop the data in JSON format and allows users to view and make modifications to the data part only.
  3. More Options: This tab contains collapsible sections with various options for manipulating the output. These options include Output Options, PDF Options, Logging Options, and IPP Options.
  4. Check JSON: It allows users to view and modify the entire JSON. The JSON displayed here is entirely sent to AOP for processing. Also, the changes made from the other three tabs are reflected here.

After loading the JSON, it can be seen in the Check JSON tab. Clicking on the PROCESS button sends the JSON to the AOP server for processing. Once the processed output is received, the Result Section displays the output file. In case the file couldn't be processed, an error message is received instead.

Logging​

Clicking on the LOGGING button (in the upper right corner) reveals the logging interface, where users can retrieve and view logs. After clicking the FETCH button, information related to print logs is displayed, providing details and insights about the logs as shown below.

Users can also sort, search and filter logs from the table header. It also allows conversion of timezone for logs time, change in units for time & file size, downloading logs in JSON & CSV, and showing Statistics of the logs.

Utility​

Also, the utility button beside the logging button provides multiple options like checking supported file types for template and other files, version query, IPP Check, Server Stats, Download the polled file, Template Hash Tools, and displaying different logs.