Using the Admin API for Scripted and Remote Management

ArcESB includes an Admin API that can be used to manage the application via scripted tasks and from a distance. All the management tools available in Arc’s web UI can also be used via one or more requests to the Admin API.

This guide will give an overview of Admin API authentication, the Resources and Actions available, and provide examples of specific uses cases and their associated API requests.

API Authentication
API Resources
API Actions
Resource Filtering
- Selecting Specific Fields
- Ordering
API Examples
- Insert a File into the Workflow
- Retrieve the Log File for a Specific Transaction

API Authentication

API Users are authorized via Auth Tokens that are generated within the application. The list of authorized Users and associated Auth Tokens are found in the Profile page of the administration console under the Security tab.

To generate a new User/Token combination, click the +Add button and specify which HTTP methods (GET, POST, PUT/MERGE/PATCH, DELETE) are allowed for this user.

Auth Tokens can be used within API requests in several ways:

Include an x-arcesb-authtoken header in the HTTP request with the value set to an appropriate User’s Auth Token
Treat the User and Auth Token as a username/password combination for HTTP Basic Authentication
Include the Auth Token in the request URL as a query parameter

To include the Auth Token in the request URL, the AllowAuthTokenInURL setting must be enabled. This option is below the table of authenticated API users in the Security tab. Once this is enabled, the syntax of the Auth Token query parameter is as follows: ‘@authtoken=myAuthTokenValue’

API Resources

Resources are objects exposed in the Admin API that can be queried, created, updated, and deleted. These Resources include:

Files - Retrieve files in the application workflow, or push files into the application workflow (by adding them to a connector’s input folder)
Certificates - Retrieve or update the digital certificates used for encryption, signing, decryption, verification, SSL/TLS, and more
Connectors - Retrieve or update the configuration for existing connectors, or add a new connector to the application workflow
Transactions - Retrieve metadata from the Transaction Log, where successful and failed file transmissions (send and receive) are recorded
Logs - Retrieve log data from the Application Log, where application-level errors are recorded
Profile - Retrieve or update the configuration for the application’s local profile
Requests - Retrieve log data from the Access Log, where HTTP requests are recorded

Each Resource is exposed at a dedicated application endpoint, using the following convention: /api.rsc/resourceName. For example, if Arc is hosted on ‘mydomain.com’ and listening on port 8001, the following endpoint would be used to access the Files Resource:

http://mydomain.com:8001/api.rsc/files

This following subsections describe the HTTP methods used to perform operations on the Resources exposed by the Admin API.

GET

An HTTP GET request can be used to retrieve a resource or set of Resources from Arc. GET requests may return multiple items or only a single item, depending on whether query parameters are specified in the request.

GET Requests Without Parameters

GET requests that do not include query parameters will return all instances of that resource type. For example, if a GET request without query parameters is made to the Certificates Resource, the response will include every certificate saved in the application; a similar request to the Connectors Resource will return configuration data for every configured connector instance in the Arc Flow.

The target URL for GET requests without parameters should be the same as the resource endpoint:

GET http://mydomain.com:8001/api.rsc/certificates

GET Requests With Parameters

GET requests can include query parameters in the target URL to limit the result set to a single instance of the target resource. For example, a GET request to the Files Resource could include the specific connector, Folder, and Filename parameter to retrieve a single file processed by that connector. Query parameters are specified in parentheses at the end of the target URL, for example:

GET http://mydomain.com:8001/api.rsc/files(connectorId='myConnector',Folder='Receive',Filename='myFile.txt')?@authtoken=myAuthTokenValue

The available parameters for each resource are detailed in the API Browser within the application UI.

POST

An HTTP POST request can be used to create a new instance of the specified Resource within Arc. For example, making a POST request to the Files Resource would insert a file into to the Arc Flow, and making a POST request to the Connectors Resource would create a new configured connector in the flow.

The parameters for the new resource are provided as the body of the POST in JSON format. The request must include the appropriate content-type header (e.g. application/json) for the POST body to be interpreted correctly. The available properties for each resource are detailed in the API Browser within the application UI. The following is an example POST body for the Connectors Resource:

{
	"ConnectorId":"myNewConnector",
	"ConnectorType":"Zip",
	"Workspace":"Default",
}

The Connectors Resource also supports additional properties according to the specified ConnectorType. Any configurable connector field can be set during the POST call by including the field name and value in the JSON body. For example, when creating a new Zip connector, the ‘Operation’ field of the connector could be set to Decompress:

{
	"ConnectorId":"myNewConnector",
	"ConnectorType":"Zip",
	"Workspace":"Default",
	"Operation":"Decompress"
}

The target URL for POST requests should be the same as the resource endpoint:

POST http://mydomain.com:8001/api.rsc/connectors

PUT

An HTTP PUT request can be used to update an instance of the specified resource within Arc. For example, making a PUT request to the Connectors Resource would update the settings for a single configured connector in the Arc flow.

PUT requests require a combination of query parameters in the target URL and properties in the JSON body of the PUT. The query parameters in the URL determine which instance of the resource to update (e.g. which connector to update) and the JSON properties determine what fields are updated within that resource (e.g. what connector configuration fields should be set to new values).

Query parameters are specified in parentheses at the end of the target URL, for example:

PUT http://mydomain.com:8001/api.rsc/connectors(ConnectorId='myZipConnector')

The JSON body of the request includes resource-specific fields to update for the target resource instance. The request must include the appropriate content-type header (e.g. application/json) for the PUT body to be interpreted correctly.

Below is an example JSON body for a PUT request to update the ‘Operation’ field of a Zip connector instance:

{
  "Operation":"Compress"
}

DELETE

An HTTP DELETE request can be used to remove an instance of the specified resource from Arc. For example, making a DELETE request to the Files Resource would delete a file from the Arc workflow.

DELETE requests include query parameters in the target URL to identify the instance of the resource to delete. Query parameters are specified in parentheses at the end of the target URL, for example:

DELETE http://mydomain.com:8001/api.rsc/files(connectorId='myConnector',Folder='Send',Filename='myfile.txt')

The available parameters for each resource are detailed in the API Browser within the application UI.

API Actions

API Actions extend the set of operations that can be performed on resources, and can also execute operations unrelated to specific resources. Actions are always invoked via an HTTP POST.

Each Action is exposed at a dedicated application endpoint, using the following convention: /api.rsc/actionName. For example, if ArcESB is hosted on ‘mydomain.com’ and listening on port 8001, the following endpoint would be used to access the archiveLogs Action:

POST http://mydomain.com:8001/api.rsc/archiveLogs

The parameters of the Action are specified in the JSON-formatted body of the HTTP post. The request must include the appropriate content-type header (e.g. application/json) for the POST body to be interpreted correctly. The available parameters for each Action are detailed in the API Browser within the application UI.

The Admin API includes the following Actions:

ArchiveLogs - Move log data from the application database into an archive file on disk.
CopyConnector - Create a new Arc connector using an existing connector configuration
CreateCert - Create a new digital certificate (public/private key pair) for encryption, signing, decryption, verification, SSL/TLS, etc.
DeleteLogs - Remove log data from the application database
DeleteTransactions - Delete log data from the Transaction Log
DownloadFile - Instruct a specified connector to download/receive a specified file (or all applicable files based on the connector’s configuration)
ExchangeCert - Update a connector’s digital certificate
GetTransactionLogs - Retrieve detailed Transaction Log data for a specific transaction
ImportProfiles - Add profiles settings, connector settings, or workspace settings to Arc from a zipped configuration archive
RefreshTransactions - Rebuild the transactions cache for a specified connector to ensure the Transaction Log data is current
RestartFile - Restart the outgoing transmission for a file being sent by a connector
SendFile - Instruct a connector to process (upload, send, transform, etc) a file in that connector’s input folder.

Resource Filtering

The Admin API supports OData filtering to retrieve specific sets of Resources. OData filters are set as the ‘$filter’ query parameter in the target URL. The following logical operators can be used to build OData filters:

eq - Equal to
ne - Not equal to
gt - Greater than
ge - Greater than or equal to
lt - Less than
le - Less than or equal to
not - Negation

For example, the following API request would retrieve Transaction Log metadata for all transactions after August 26th, 2019:

GET http://mydomain.com:8001/api.rsc/transactions?$filter=timestamp gt 2019-08-26

OData filters can be combined with the ‘and’ and ‘or’ keywords. For example, the following API request would retrieve all Transaction Log metadata for a specific connector’s transactions after August 26th, 2019:

http://mydomain.com:8001/api.rsc/transactions?$filter=timestamp gt 2019-08-26 and connectorid eq myConnector

The Admin API also supports the following functions inside of an OData filter:

startswith(property, ‘value’) - Resources will only be returned if the specified property begins with the specified value
endswith(property, ‘value’) - Resorces will only be returned if the specified property ends with the specified value
contains(property, ‘value’) - Resources will be only be returned if the specified property contains the specified value

For example, the following API request retrieves Transaction Log metadata for all XML files processed by the application:

GET http://mydomain.com:8001/api.rsc/transactions?$filter=contains(filepath,'.xml')

Selecting Specific Fields

In addition to the ‘$filter’ query parameter, the ‘$select’ query parameter can be set to limit the specific fields that are returned in the response. This parameter should be set to a comma-delimited list of the properties to retrieve. For example, the following API request retrieves the name and workspace of each configured connector, but none of the other configuration details of these connectors:

GET http://mydomain.com:8001/api.rsc/connectors?$select=connectorid,workspace

The API also supports retrieving a single value from a single resource, for example the following API request returns the workspace for a specific connector:

http://localhost:8001/api.rsc/connectors('myConnector')/workspace/$value

Ordering

In addition to ‘$filter’ and ‘$select’, the ‘$orderby’ query parameter can be set to sort results into a specific order. This parameter is specified with the following syntax:

$orderby=columnName sortDirection

Where ‘columnName’ is the column to use for sorting (e.g. filename, connectorId, timestamp, etc) and ‘sortDirection’ is either ‘asc’ for ascending or ‘desc’ for descending.

For example, the following API request retrieves Transaction Log metadata for all XML files processed by the application, then groups the results according to whether the files were ‘sent’ or ‘received’:

GET http://mydomain.com:8001/api.rsc/transactions?$filter=contains(filepath,'.xml')&$orderby=status asc

Multiple ordering conditions can be specified by setting the ‘$orderby’ parameter to a comma-delimited list (conditions earlier in the list take precedence). For example, the following API request retrieves the same data as the previous request, but within the ‘sent’ or ‘received’ groups the files are listed largest-to-smallest:

GET http://mydomain.com:8001/api.rsc/transactions?$filter=contains(filepath,'.xml')&$orderby=status asc, filesize desc

API Examples

This section contains common use cases that require a combination of API requests to accomplish.

Insert a File into the Workflow

POSTing to the Files Resource adds a file to the ‘Send’, ‘Receive’, or ‘Sent’ folder for a particular connector. To insert a file into the workflow, POST the file to the ‘Send’ folder for the first connector that should process the file. For example:

POST http://mydomain.com:8001.com/api.rsc/files

{
    "ConnectorId":"myConnector",
    "Folder":"Send",
    "Filename":"test.txt",
    "Content":"VGhpcyBpcyBhIHRlc3Qu"
}

Note that the ‘Content’ parameter includes the base64-encoded content of the file.

If the target connector has Send Automation enabled then the file will automatically be processed. Otherwise, an additional call to the sendFile Action is required to instruct the connector to process the file. For example:

POST http://mydomain.com:8001/api.rsc/sendFile

{
  "ConnectorId":"myConnector",
  "File":"test.txt"
}

Retrieve the Log File for a Specific Transaction

The getTransactionLogs Action retrieves the log file for a specific action. Invoking this Action requires knowing the MessageId for the relevant transaction. The MessageId can be found by querying the Transactions Resource first (the Transactions Resource returns metadata about the transaction, but not the transaction log file itself).

The GET query to the Transactions Resource should include any filters necessary to identify the specific transaction (unless the result set can be parsed by some other process to find the MessageId for the desired transaction), for example:

GET http://mydomain.com:8001/api.rsc/tansactions(connectorId='myAS2Connector',Filename='myFile.edi')

The JSON body of the response will include the MessageId for the specific transaction. Use this MessageId in the getTransactionLogs call, along with the other required parameters ‘ConnectorId’ and ‘Direction’ (Send or Receive). The ‘Include Content’ parameter should be set to ‘True’ to include the contents of the log file in the response. For example:

POST http://mydomain.com:8001/api.rsc/getTransactionLogs

{
	"ConnectorId":"myConnector",
	"Direction":"Send",
	"MessageId":"message_id_from_earlier",
	"IncludeContent":"True"
}

The ‘Content’ parameter of the response will hold the base64-encoded log file contents.

Ready to get started?

Learn more about ArcESB or download the free single-connector license:

Download Now