Sign In

AppSynergy REST API

The AppSynergy REST API can be broken down into three different categories of services.

Inbound Web Requests

Allow your database to accept custom inbound web requests (i.e. publish APIs for others to use).

PDF Document Generation

Used to dynamically generate PDF documents from database data. This service is typically called from your PL/SQL code via an Outbound Web Request.

Executing SQL

Used to allow other applications to issue SQL commands against your database via a REST interface. You can also allow other systems to connect securely to your database via ODBC or JDBC.

API Keys

In the examples below YOUR_API_KEY and its assigned Security Role determine access rights (see Tools > API Keys...). YOUR_API_KEY can be provided as a URL parameter (as shown below) or alternatively as an HTTP header in Bearer Authentication format.

Note that all actions:

WEB_REQUEST – Accept an inbound web request

Each http request is inserted into the WebRequest table in your database. Your code then sets the resp_code and resp_body fields to appropriate values when your trigger runs; an example is shown below.

Request

GET | POST https://www.appsynergy.com/api?action=WEB_REQUEST&apiKey=YOUR_API_KEY&OptParam=SomeValue { "AnyValidJson": "OK" }

Your trigger will see the request data as follows:

Response

{ "AnyValidJson": "OK" }

Your trigger should SET the response fields as follows:

Trigger Example - BEFORE UPDATE on WebRequest

Your BEFORE UPDATE trigger on the WebRequest table should look something like this:

BEGIN -- only respond if resp_code is NULL IF (NEW.resp_code IS NULL) THEN -- verify the request is from a valid API user IF (NEW.req_user_id != 'u1234') THEN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Permission Denied.'; END IF; -- parse req_params and/or req_body and generate your response IF (JSON_VALUE(NEW.req_params,'$.TestMe') = 'true') THEN SET NEW.resp_code = 200; SET NEW.resp_body = JSON_OBJECT('MyResponse','Hello World'); ELSE SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Invalid Request. Try this: TestMe=true'; END IF; END IF; END

Your trigger will be fired once (and possibly twice) for each web request received. The first update will have NEW.resp_code set to NULL; your code should test for this NULL value and respond appropriately by setting the NEW.resp_code and NEW.resp_body fields to appropriate values.

If, during the first update, your code encounters an error (or raises a SIGNAL to indicate an error) the transaction will automatically be rolled back in its entirety. The system will then update the row a second time, in a new transaction, with a non-null resp_code and resp_body to log the error.

EXEC_QUERY – Execute an SQL Query

Executes an SQL query and returns the results in either JSON or CSV format. You can execute an SQL command like SHOW TABLES to see which tables are available.

Request

POST https://www.appsynergy.com/api?action=EXEC_QUERY&apiKey=YOUR_API_KEY { "sqlCmd": "SELECT * FROM MyTable", "responseFormat": "JSON" }

Response

If responseFormat was CSV:

Customer_ID,Name 1000,"Company A" 1001,"Company B"

If responseFormat was JSON:

{ "status": "OK", "errorMessage": "", "errorCode": "", "data": { "columns": [ { "tableName": "Customers", "columnName": "Customer_ID", "datatype": "BIGINT" }, { "tableName": "Customers", "columnName": "Name", "datatype": "VARCHAR" } ], "rows": [ { "values": [ { "value": "1000" }, { "value": "Company A" } ] }, { "values": [ { "value": "1001" }, { "value": "Company B" } ] } ] } }

EXEC_DML – Execute an SQL DML Statement

Executes an SQL DML statement (e.g. INSERT, UPDATE, DELETE) and returns the number of rows affected.

Request

POST https://www.appsynergy.com/api?action=EXEC_DML&apiKey=YOUR_API_KEY { "sqlCmd": "UPDATE MyTable SET MyCol = 123 WHERE ID = 100" }

Response

{ "status": "OK", "errorMessage": "", "errorCode": "", "data": { "rowsAffected": 1 } }

HTML2PDF – Generate a PDF doc from HTML

Generates a PDF document from the provided HTML and stores it in your database storage bucket. The response contains a reference to that document in AppSynergy Document Field format. Often used to generate invoices, purchase orders, etc.

Request

POST https://www.appsynergy.com/api?action=HTML2PDF&apiKey=YOUR_API_KEY { "html": "<html><body><h1>Hello World</h1></body></html>", "filename": "HelloWorld.pdf", "makePublic": false }

Response

{ "status": "OK", "errorMessage": "", "errorCode": "", "data": { "documentField": "HelloWorld.pdf;1048;1598992707098;database/files/a655f610-febd-4f6a-b11d-6bcd696f5456.pdf" } }

Example

See the PDF Generation Example for details on how to call this service from your AppSynergy code.

PDF_AUTOFILL – Auto fill a template PDF doc

Given a fillable PDF document as a template, and a list of field names and values, this method fills in the PDF fields creating a new filled PDF document.

Request

POST https://www.appsynergy.com/api?action=PDF_AUTOFILL&apiKey=YOUR_API_KEY { "sourcePdf": "MyFillableTemplate.pdf;1048;1598992707098;database/files/a655f610-febd-4f6a-b11d-6bcd696f5456.pdf", "dataFields": { "field1":"value1", "field2":"value2" }, "outputFilename": "MyNewDoc.pdf", "ignoreMissingFields": true, "flattenFields": "NONE" }

Response

{ "status": "OK", "errorMessage": "", "errorCode": "", "data": { "filledPdf": "MyNewDoc.pdf;12048;1598992709098;database/files/a655f610-febd-4f6a-b11d-6bcd696f5466.pdf", "acroFieldNames": [ "FirstName", "LastName" ] } }

PDF_MERGE – Merge multiple PDF docs into a single PDF

Merges multiple PDFs into a single document.

Request

POST https://www.appsynergy.com/api?action=PDF_MERGE&apiKey=YOUR_API_KEY { "outputFilename": "MyNewDoc.pdf", "sourcePdfs": [ "Doc1.pdf;10428;1598992706098;database/files/a655f610-febd-4f6a-b11d-6bcd696f5456.pdf", "Doc2.pdf;21048;1598992507098;database/files/a655f610-febd-4f6a-b11d-6bcd696f6bcd.pdf", "Doc3.pdf;90148;1598992737098;database/files/a655f610-febd-4f6a-b11d-6bcd696f4f6a.pdf" ] }

Response

{ "status": "OK", "errorMessage": "", "errorCode": "", "data": { "mergedPdf": "MyMergedDoc.pdf;91048;1598992709098;database/files/a655f610-febd-4f6a-b11d-6bcd696f5466.pdf" } }