6.2. The IDERI note REST API

The IDERI note REST API is part of IDERI note web. While there are many different ways of how to consume an API, we only point out a few ways of how to work with the IDERI note REST API in this chapter.

6.2.1. Swagger™ UI

The IDERI note REST API makes use of the Swagger™ UI API interface. It provides a browsable API for most of its endpoints, which you can inspect at http://<host>:<port>/IDERInote/api/.

Warning

IDERI note web uses IIS basic authentication by default. Using basic authentication over http is not secure as the credentials sent to the server are not encrypted. Therefore you should configure the IIS web site where IDERI note web has been installed to always use HTTPS/TLS. (See chapter 3.15.3.3)

When using an internet browser to connect to the API you will get prompted for your domain credentials (figure 6.18).

Figure 6.18: Authentication prompt for API

When successfully authenticated you will get an overview of all the endpoints available in the API (figure 6.19).

Figure 6.19: Swagger™ UI for the API

When you click on an endpoint in Swagger™ UI you can inspect the request schemas and given parameters (figure 6.20). You can also execute a request directly in Swagger™ UI by selecting Try it out.

Figure 6.20: Swagger™ UI details for GET message

6.2.2. PowerShell

You can use Windows PowerShell to consume the API as well. To do so, use the CmdLet Invoke-RestMethod.

The following example demonstrates how to query for license information from the associated IDERI note server using the API and PowerShell.

PS> $URI = "https://note-srv07.note.dev/IDERInote/api/v1/licenses"
PS> Invoke-RestMethod -Method Get -Uri $URI -Credential (Get-Credential)


licenseMode                   : 2
desktopLicenses               : 55
desktopLicensesUsed           : 1
desktopClientConnections      : 1
desktopUserConnections        : 1
desktopComputerConnections    : 0
desktopLicenseRequestsRefused : 0
mobileLicenses                : 57
mobileLicensesUsed            : 0
mobileClientConnections       : 0
mobileLicenseRequestsRefused  : 0

The next example shows how to create a new message with the priority ALERT and a validity of 1 hour from now on.

PS> # The API uri
PS> $URI = "https://note-srv07.note.dev/IDERInote/api/v1/messages"
PS>
PS> # Create an array for the recipients
PS> $recipients = @("homer.simpson","bart.simpson")
PS>
PS> # Create the message as a hash table
PS> $msgObj = @{
        Text = "Hello world"
        StartTime = (Get-Date -Format O)
        EndTime = ((Get-Date).AddHours(1).ToString("O"))
        Priority = "ALERT"
        Recipient = $recipients
        ShowPopup = $true
    }
PS> # Convert the message hash table to a json string
PS> $msgJson = $msgObj | ConvertTo-Json -Compress
PS>
PS> # Consume the API
PS> Invoke-RestMethod -Method Post -Uri $URI -Credential (Get-Credential) `
    -Body $msgJson -ContentType "application/json"

6.2.3. curl

The next example uses curl to query IDERI note license information from the IDERI note REST API. The --insecure parameter of curl ignores the SSL certificate.

curl -X 'GET' 'https://note-srv07.note.dev/IDERInote/api/v1/licenses' \
    -H 'accept: text/plain' -u 'note.dev\homer.simpson' --insecure