SecureTransport 5.5 introduced a new version of the REST API - version 2.0. It improved on top of the existing version 1.4 and added or shifted functionality. This article aims to briefly outline the main differences between the two versions of the API.

PATCH method

REST API 2.0 supports the PATCH method for updating objects. So far, if you wanted to update a single attribute of an object, you had to GET the entire object, modify a single value and POST/PUT back the whole object again.

Now PATCH gives you the ability to specify the exact attribute and its value.

Here is an example, how you can change the login name of an account john to john_new:

PATCH "https://<HOSTNAME>:<PORT>/api/v2.0/accounts/john"
-H "accept: */*" -H "Content-Type: application/json"
-d "[{\"op\":\"replace\",\"path\":\"/user/name\",\"value\":\"john_new\"}]"

Usage

The following main fields of the JSON object above are of importance:

The Operation (field op) could be one of replace, add or remove.

Use replace to update an available value, add to add a missing value and remove if you want to delete it.

The Path (field path) is absolute to the value you want to modify. Here is an example to illustrate the idea.

GET for account returns:

{
   "name": "john",
      ...
      "user": {
            "name": "john",
            "secretQuestion": {
                  "secretQuestion": null,
                  "secretAnswerGuessFailures": 0,
                  "forceSecretQuestionChange": false
             },
       }
      ...
}

Path is "/name" if we want to modify the Account's name.

Path is "/user/name" if we want to modify the Login User's name.

Path is "/user/secretQuestion/secretQuestion" if we want to modify the Secret Question of the Account.

The Value (field value), applicable for add and replace operations, represents the new value you want to apply.

One Account object

In SecureTransport's REST API 1.x versions, you had to execute at least 2 queries to create an account with its respective user. Now the POST /accounts methods allow you to create an Account and a User with a single query. In addition to that, the resource is extended to cover a lot more.

{
    "type": "user",
    "name": "john",
    ...
    "user": {...},
    "addressBookSettings": {...},
    "adhocSettings": {...},
    "accountMaintenanceSettings": {...},
    "fileMaintenanceSettings": {...},
    "bandwidthLimits": {...},
    "additionalAttributes": {},
    "metadata": {...}
}

Usage

You can select among one of our standard available methods.

GET /accounts will give you a collection with all available End Users.

POST /accounts is the resource with which you can create an account per call.

HEAD /accounts/{name} to check if an account with the specified name exists.

GET /accounts/{name} to get the attributes of the specified account.

PUT /accounts/{name} to override all attributes of the specified account.

PATCH /accounts/{name} to partially update the attributes of the specified account.

DELETE /accounts/{name} to delete the account with the specified account.

Here is an example with the mandatory attributes for an Account creation

{
    "name": "john",
    "uid": "1001",
    "gid": "1001",
    "type": "user",
    "homeFolder": "/home/john",
    "user": {
        "name": "john",
        "passwordCredentials": {
            "password": "1"
        }
    }
}

One generic Logs resource

Instead of navigating to different locations in the REST API swagger to find a common set of information - logs, you can now find them all under the /logs resource.

As you can see from the screenshot here we have combined the Audit Log, Server Log, and Transfers Log.

Usage

If it is hard to use - then we did it wrongly! Please let us know and help us improve the API experience. The methods and resources are supposed to be self-explanatory and should not need more details.

Content-Type instead of export

One of the main checks the REST API Validation tools are performing is for verbs in the name of the resources. Compared to 1.4, we have removed 5 export resources:

/auditLog/export
/logs/export
/certificates/export
/transfers/export
/zones/{name}/edges/{title}/certificates/export

Usage

Our fix is simple and easy to remember - just use the respective GET resource with the content-type header, i.e.

GET /logs/audit
GET /logs/server
GET /certificates
GET /logs/transfers

Operations resource instead of verbs

Start, stop, test, cancel, resubmit, verify, pull - number of different verbs we are having in REST API 1.x. To improve the picture, we've decided to introduce a new concept called Operations. Operation resources that are structured in the same way across all resources, to improve the learning curve, understanding, and ease of use.

Usage

The general rule is

POST /<resource>/operations?operation=<name_of_the_operation>

So instead of /transfers/pull, we have POST /transfers/operations?operation=pull. Instead of /daemons/operations/start, we have POST /daemons/operations?operation=start.

Result Set instead of count resource

We've removed the /*/count resources in 2.0 that are still present in 1.x. Instead, we have a result set for all GET requests that are working on a collection of entries:

"resultSet": {
       "returnCount": 4,
       "totalCount": 4
}

Usage

The response body of the GET requests is starting with the above type of element. It has two fields - returnCount and totalCount.

totalCount represents the number of all available objects.

returnCount is the number of elements you've received in the response. It is affected either by the specified limit value (by default it is 100) or by given search criteria. By search criteria understand "All Transfer Sites where the protocol is HTTP", i.e. GET /sites?protocol=HTTP.