How to start using APIs with your MFT solution

APIs can be a powerful asset in your MFT toolkit. Today, virtually everything communicates via REST APIs – they are light, efficient, and easy to use. They are easy to expose, understand, and update. And API management tools and marketplaces allow information to be centralized, even acting as a repository to access and consume MFT services.

One of the great advantages of APIs is that you can embed them into your own applications. For example, you might have a business process for onboarding new clients or file transfer workflows. You can set up your application to obtain all the necessary approvals and issue a set of APIs to automatically create your workflow.

If you’re not using Axway SecureTransport APIs yet, this article will help you get started. But first, a few basics on how APIs and MFT can be used together.

How are APIs used for file transfer?

There are many ways modern file transfer solutions leverage APIs to enable more comprehensive integration capabilities. Here are two examples:

1. Use APIs to configure and provision file transfers

Create, update, and deploy a file transfer route at the same time the application requires it, which introduces the file transfer within the application lifecycle and the MFT service within the DevOps initiative.

Integrate provisioning of partners with workflow and applications, managing the partner lifecycle to ease onboarding and maintain information accuracy over time.

2.  Use APIs to integrate applications

The file that is being transferred within the business process, such as an order created through a business application, triggers a file transfer to send the bill of material to the logistician.

The interface application doesn’t need to rely on technical MFT parameters. The MFT service is designed to translate the business ID into the appropriate technical parameters to initiate the transfer.

This blog describes an MFT-API hybrid integration example that could be used in healthcare.

So, how can you leverage the full power of SecureTransport with APIs? Let’s dive in with some use cases and demos.

How to use APIs for secure file transfer with Axway SecureTransport

V5.5 of SecureTransport introduced the V2.0 set of REST APIs, which are a much cleaner and well-structured set of standards than the prior ones used in the previous version V5.4. If you haven’t made the upgrade yet, we recommend you do so as soon as possible to benefit from the best functionality.

Most of the things you can accomplish through the admin UI are possible using APIs, but there are some things that you cannot do through the UI, which are only possible with APIs.

SecureTransport comes with two sets of APIs, administrative APIs and user APIs. For this article, we’ll focus on the admin APIs.

Both sets have an integrated Swagger Interface within SecureTransport – You don’t need to remember the URI – just click on the dropdown as shown and you’ll enter the Swagger UI.

You’ll notice that the APIs correspond to pages and objects within the UI, such as accounts, sites, subscriptions, certificates, etc. Please note that this link is for the Admin REST API – the link for the user API is available from the Web Client.

Here we see the accounts API, and clicking the arrow exposes the methods that the API supports.

ST Admins can use the GET methods directly from here – no programming knowledge required!

Using an API to query

The GET method can be very useful for quick queries of your system. For example, what if you wanted to know how many accounts exist for a particular Business Unit?

This would be a little messy to accomplish via the UI if you have many screens’ worth of accounts. But using the APIs, this is easy!

The following video clip demonstrates how to use fields in queries to accomplish this.

Here is the JSON response to the query we just issued – we’ve found 4 accounts that belong to the BU called Pippin.

SecureTransport will only return JSON responses in V2.0 APIs. JSON (Javascript Object Notation) consists of a set of objects with Key : Value pairs separated by commas.  It can also be an array of objects delimited by square brackets – so this example is about as complicated as it gets for JSON which is why it is used so often

Notice that the Swagger UI also allows us to download the response to your PC, which can be useful if you need to use it in another program, add it to a report or a powerpoint or deliver it to a customer or a collegue.

A note about authentication in curl vs shell script

The Swagger UI provides a Unix command line curl equivalent command. This is useful, as it allows you to embed the commands in shell scripts, for example.

However, be warned: the curl equivalent shown is missing the authentication piece.

Swagger UI gives this:

curl -X GET

'https://catco.axway.university:8444/api/v2.0/accounts?fields=name,businessUnit&businessUnit=Pippin' –H 'accept: application/json’

In a shell script you will need this:

curl -k -u 'APIadmin:Axway123' -X GET 'https://catco.axway.university:8444/api/v2.0/accounts?fields=name,businessUnit&businessUnit=Pippin' –H 'accept: application/json’

curl -k --key /opt/software/certs/catco_client.pem --cert /opt/software/certs/catco_client.crt -X GET 'https://catco.axway.university:8444/api/v2.0/accounts?fields=name,businessUnit&businessUnit=Pippin' –H 'accept: application/json'

The –k takes care of you maybe not using a trusted Certificate in ST for your admin, and the –u is your admin username password.

We always recommend you use a separate admin account for APIs, so here we have a Master Admin account called APIadmin.  This is using Basic Authentication in API terminology, i.e. username password.

(This would not be recommended for your production systems – we are showing it here just as a demonstration.)

SecureTransport also supports Certificate-Based Authentication – that would be the preferred method to use in production scripts and code. We show the curl syntax for this here as an example.

Formatting an API request

The format of any API request to any product is basically as follows:

HTTPS method (i.e. GET) for a read, POST/PUTfor a write or create.

URI (path to the resource/object + optional qualifiers:

• 1^st qualifier is ?
• 2^nd and subsequent qualifier is &

Headers i.e. accept or Content-Type, etc.

GET https://yourserver:port/api/resourceid?qual1=x&qual2=Y

Creating SecureTransport objects

Using the POST method, we need to add a Header and the content that we wish to use in JSON format.

See below for a simple JSON message for creating an account.

In this example, we are using a separate file to store the JSON just for clarity, but you can also embed it in the command line if you wish.

curl -k -u 'APIadmin:Axway123' -X POST 'https://catco.axway.university:8444/api/v2.0/accounts' –H 'accept: application/json’ –H ‘Content-Type: application/json’ -d @json.filename

Contents for json.filename

{

    "name": "3_2_FM_TO_SSH",

    "type": "user",

    "homeFolder": “/usrdata/NoBU/3_2_FM_TO_SSH",

    "uid": "7001",

    "gid": "7000",

    "user": {

        "name": "3_2_FM_TO_SSH",

        "authExternal": false,

        "passwordCredentials": {

            "password": "Axway123"

        }

    }

}

Account onboarding using a SecureTransport API

Now that we know how to create ST objects, it’s time to take advantage of APIs to embed them into your own applications.

We’ll use the example of a business process for onboarding new clients or file transfer workflows.

Your application can obtain all necessary approvals and finally issue a set of APIs to automatically create your workflow on ST.

Just about any scripting language or programming language supports APIs these days. Here’s an API flow that could create using the UI and individual account objects such as transfer sites, subscriptions, etc.

Here are the APIs required to add the advanced routing part to the sequence.

However, this API flow can be much simplified using a special API called accountSetup. Take a look at the sequence diagram below:

As you can see, it is much simpler in terms of the number of APIs issued – though the JSON is a little more complex!

Let’s onboard a file transfer flow that uses the following objects. The input is a folder monitor, which transfers files outbound via an SFTP transfer site.

We’ll use POSTMAN to issue the APIs. You can use any other software and/or programming language. You can see a demonstration of this in the following video.

You can also recreate that same flow using the accountSetup API. Watch the following video for a quick demo of how this would work.

Remediate system configuration drift with APIs

Now, let’s examine a use case that almost everyone can use: checking for system configuration drift.

All of the admins who are on your system are going to run things on it, and this will inevitably cause some level of drift of the configuration compared to a new system or any documentation. In addition, updates and upgrades can add new elements into the configurations which differ from the previous state.

This next example is a great way of spotting any changes to the system made by your app.

It requires issuing multiple APIs to accomplish the task, but it is extremely useful from a control and governance perspective.

We’ll be reading all the live system configuration settings and comparing them to a reference that we established beforehand. Any differences between the live system and the reference values will be flagged.

In this example, we’re using a python script to accomplish the task, but you could implement this however you like.

[axway@catco python3] $ ./stConfigScan.py COMPAREBASELINE

Program called with argument COMPAREBASELINE

Starting at 2024-03-06 18:15:24.797805

Number of CPUs available to this server: 4

Commencing Run Using 10 threads

Session Login

Admin.AllowedFormPostParameters with value [‘id_token;access_token’] does not exist in the baseline

Admin.Security.PermissionsPolicy with value [”] does not exist in the baseline

Http.Security.PermissionsPolicy with value [”] does not exist in the baseline

TransactionManager.ThreadPools.ThreadPool.EventMonitor.maxQueueSize.usageAlertsLogging with value [‘disabled’] does not exist in the baseline

Session Mgt Logged Out

Completed Run. Number of APIs issued: 12

(Note: this is what you would see when you upgrade to the February 2024 patch from the January release, where some new system parameters were added.)

This flow is extremely helpful for seeing any unauthorized system config changes that might have taken place. We highly recommend that you put a similar process in place on your own sites if you don’t currently do so.

See also secure file transfer: Prevent & prepare vs. repent & repair

Pulling new files from a remote site

Finally, let’s demonstrate a use case that isn’t possible using only the user or admin interface.

Let’s say you have been asked to configure a flow to perform a file pull from a remote site – but you only wish to pull files that are older than a preset time.

This is easy to implement via the UI if the filename itself contains the date time stamp – not so easy if it doesn’t!

You could certainly do this manually, by using the LIST button on an SFTP transfer site and obtaining a list of file names and their creation date. But it’s not really feasible to automate this in any type of file transfer flow.

By using an API that can perform the same LIST functionality as the UI’s manual LIST, however, this becomes easy!

POST {{stURL}}/sites/operations?operation=listRemoteFolder&folderToList=downloadFolder

Now, we can programmatically scan the returned JSON last modifiedTime fields and select the filenames we need.

Then, we can use another API to trigger a pull of the specific filenames required:

${DXAGENT_TRANSFERSAPI_PULLFILEPATTERN}

In our transfer site, we use the variable as shown in the Download Pattern.  This means that the value – i.e. the required filename – can be set by the triggering API.

{{stURL}}/transfers/operations?operation=pull

Note the addition of the custom property PULLFILEPATTERN – this becomes the TRANSFERSAPI variable name we just saw.

Conclusion

This has been a very quick tour of SecureTransport APIs and some of the myriad capabilities. We invite you to visit our Developer Guide to discover more useful REST API URIs.

Axway MFT is an API-powered enterprise file transfer solution that leverages multi-nodes, automation, monitoring, and cloud-enabled transfer of any mission-critical files.

You’ll enjoy complete business-level REST APIs that allow you to integrate third-party or custom applications.

We hope this brief overview of some to use these APIs has been helpful, and please don’t hesitate to reach out if you need more help getting started with SecureTransport APIs. You’ll find more resources on Axway University as well.