API Beginners Guide

Some functionality on the Cimar platform in not available in the UI and can only be access by an "API Call", a few guides within our https://support.cimar.co.uk/ will ask you to make a call, and provide you with the parameters to do so. This guide allow you to take that information and "Make the Call".

Please read the "Best Practices" section before using the API Tester.

The API is an advanced tool and allows you to make changes to the Cimar interface that are not available in the UI. It will not however let you make a change that your roll does not permit from within the UI.

This guide is split into the following sections:
  1. Accessing the API
    • Public API
    • API Tester
  2. Reading the Public API Documentation
    • Table of Contents 
    • Description
    • URL
    • Parameters
    • Returns
    • Permissions
    • Notes
  3. Best Practices
  4. Making the Call

Accessing the API

The API can be access through the URL https://cloud.cimar.co.uk/api/v3 and will require you to log in using your Cimar credentials.

Once you have logged in you will see links to various features. This guide will only cover the "Public API" and "API Tester".

Public API

The "Public API" link will take you to a large document explaining everything that can be accessed via the API. This can be overwhelming at first glance so we will break it down in the next section

API Tester

The "API Tester" is where you will make your "API Calls", we will cover it in the last section of this guide.

Reading the Public API Documentation

Table of Contents

The "Public API" document starts with "The Table of Contents", items 1 - 13 are for advanced calls and troubleshooting. We will be focusing on "Session Commands", which is a list of all calls that can be made using the API. If you are following a guide and wish to view its configuration you can find the call here and have it link you to the correct part of the document.

The majority of calls in this document can be configured within the UI, Cimar guides will only show API settings where this is not the case. 

These links till take you to the call information, the call is split into 6 - 7 sections.

Description

This is a simple explanation of what the call is used for.

URL

This is what is referred to as “the call” and will be used in the section "making the call".

Note: When copying the call into the API interface remove the first / e.g.,
  • /user/password/lost → user/password/lost

Parameters

These are the input that will make changes or trigger actions and are split into two parts.

  • Name (The first part of the parameter in GREEN text)
  • Input (The second part of the parameter, usually a description of the input)

Some parameters are labeled as (optional) and are only required if you want to trigger that specific action.

Returns

This is a list of what information to expect on a successful call.

Permissions

If the call requires specific role permissions they will be listed in this section.

Errors

Is a list of possible error returns and what they mean. Common errors are 

  • MISSING_FIELDS (One or more parameters is missing, or contains incorrect information)
  • NOT_PERMITTED (You do not have sufficient role permissions to make this call)
  • 401 Authorization Required (This usually means your session has expired, you have taken too long to make the call. You will need to log out and back into the api and make the call again)

Notes

Useful information for making the call, or more information about what the call is doing.

Best Practices

get/set/get

When making an API call to change a user/role/account setting it is a good practice to use the get/set/get method, which is analogous to measuring twice, and cutting once!

This means first making a “get” call which will provide you with information on the user/role/account, allowing you to ensure you have the correct “uuid” (unique identifier). And that the setting in question has not already been set.

Next you make the “set” call which will action the required change.

Finally you make another “get” call to confirm the change has been made. This is important as the API will only show an error is the input was incorrect. It is possible to make a “set” call with an “Ok” response but change nothing.

account/get

Note: The return message is in a random order each time. It is helpful using “ctrl f” on pc or “cmd f” on mac to search for the value you need. Here I have confirmed the change I am making is in the correct account.

account/set

Note: This would then be followed by another account/get call to ensure the actual setting that was being targeted has been updated.

Suspending with the call

While Webhooks and Purge Rules are all much easier to create using the UI. Purge rules in particular have a few options that can only be updated using the API.

If you are making a webhook or purge rule with the api, it is always a good idea to user the (optional) parameter suspended e.g.,

  • Parameter: suspended
    • Value - 1

This will complete the call but ensure the webhook or purge rule does not fire until you have manually removed the suspension, allowing you the ability to return to the UI and confirm all settings are as you require before it is live.

To remove the suspension simply un-check the box from within the UI.

Making the Call

To make an API call log into the the API interface and click the API Tester link Accessing the API. This page is a list of text fields that take specific input.

Not every field is used in every call, a few are very rarely used and we will bypass them in this guide.

For this example we will be using the “purge/add” call.

Note: Remember that (optional) fields are not required to complete the call, but may be part of the call depending on your requirements.

The parameters we will be using for this call are:

  • SID
  • name
  • account_id
  • days_old
  • days_old_how
  • suspended (optional)

The first 5 are mandatory and will be required to successfully complete the call. The last “suspended” is optional but in this case we want the functionality.

Note: Remember, the first part of the parameter is copied exactly as displayed in the documentation. This is the green text. The value input will change depending on its requirement, from the example above your input would look similar to this.

With the example below we will be creating a rule that will Purge all Studies all studies 90 days after they have been uploaded.

URL

Start by inputting the call into the URL field remembering to remove the first /.

The next two sections are very rarely used and will not be covered in this guide. Leave them empty.

  • Basic auth Username
  • Basic auth Password

Parameters

  • Parameter: SID - The first “Parameter” field will be automatically populated with “SID” (session identifier) and a corresponding value. This field is a requirement for most calls and should be left un-changed.
  • Parameter: name
    • Value - Purge “Anon” studies 90 days after upload

A logical name for the Purge Rule. As we will be setting this rule to purge studies from the “Anon” namespace after “90” days we could call the rule “ Purge studies 90 days after upload”

  • Parameter: account_id
    • Value - The uuid of the account you are creating the rule for. Follow this guide to find your UUID.
  • Parameter: days_old
    • Value - 90

Studies equal to or greater than this value will be purged.

  • Parameter: days_old_how
    • Value - C

This field accepts three values we are targeting days since upload so will use “C”.

  • C (created) - days since the study was “Created” or “Uploaded”.
  • S (study date) - days since the scan.
  • U (updated) - days since the study was last updated e.g., shared, reported, viewed etc…
  • Parameters: suspended
    • Value - 1

The value for this field is a boolean “flag”. This means an input of “1” will activate the option and “0” will de-activate it.

This parameter will suspend the rule so it does not automatically run and is good practice when making a purge rule as it gives you the opportunity to double check all values.

The completed input will look something like this:

Click the “ Submit” button at the bottom of the page. This will make the call and refresh the page. At the top you will see the response.

For this call we are expecting a Status of OK and the uuid (unique identifier) of your new rule.

Remember that expected returns can be found in the documentation under the “Returns” section.

If you have any questions about API calls or need assistance with what a “return message” means. Please contact support@cimar.co.uk

Still need help? Contact Us Contact Us