REST API Documentation / Code Samples section
Idea shared by Rod Strumbel - 9/30/2019 at 4:32 PM
Under Consideration
I can't possibly be the only one learning to interact with a REST API from .Net code (maybe I am... who knows).  It would be HUGELY useful (to me anyway) to have an area where there are sets of SIMPLE code examples that do one job cleanly.

For example, I went around and around in circles today chasing my tail trying to figure out why no matter what format I sent the JSON body up to the server in, it always returned a (415) Unsupported Media Type error.  

It would have saved literally HOURS to have simply had a little bit of code that demonstrated how from a .Net application I could obtain the access token.  With EXPLICIT sample data and not just { YOUR INPUT HERE }.

So for the first item I'll post my code for that operation, it's a bit lengthy because I utilize object serialization but it is easy to follow and gets the job done.

First, this code utilizes the newtonsoft.json and the System.Net (for WebClient) library and is written in (using .Net framework 4.5.2).   And I happen to be talking to SmarterMail 100.0.7125.

Step 1:  Define the classes you will be utilizing

Class 1 - Username and Password
Public Class clsUsernamePassword
    Public Property username As String
    Public Property password As String

    Public Sub New(strU As String, strP As String)
        username = strU
        password = strP
    End Sub
End Class
Class 2 - return object for auth/authenticate-user
Public Class clsAuthenticateUser
    Public Property EmailAddress As String
    Public Property changePasswordNeeded As Boolean
    Public Property displayWelcomeWizard As Boolean
    Public Property isAdmin As Boolean
    Public Property isDomainAdmin As Boolean
    Public Property isLicensed As Boolean
    Public Property autoLoginToken As String
    Public Property autoLoginUrl As String
    Public Property isImpersonating As Boolean
    Public Property canViewPasswords As Boolean
    Public Property accessToken As String
    Public Property refreshToken As String
    Public Property accessTokenExpiration As Date
    Public Property username As String
    Public Property success As Boolean
    Public Property resultCode As Integer
    Public Property message As String
    Public Property debugInfo As String
End Class
Step 2 - Setup a management class for managing communication with SmarterMail

Public Class SmarterMailAPIClient

    Public Function DoAuthorizeAndGetAccessToken(strU As String, strP As String, 
                    strSvr As String, strAPI As String) As clsAuthenticateUser
        Dim myURL As String = strSvr + strAPI + "/auth/authenticate-user"
        Dim myClient As WebClient = New WebClient
        myClient.Headers(HttpRequestHeader.ContentType) = "application/json"
        Dim myO As New clsUsernamePassword(strU, strP)
        Dim myJson As String = JsonConvert.SerializeObject(myO)
        Dim jsonResponse As String = myClient.UploadString(myURL, myJson)
        Dim clsAuthenticateUserObject As clsAuthenticateUser = JsonConvert.DeserializeObject(Of clsAuthenticateUser)(jsonResponse)
        Return clsAuthenticateUserObject
    End Function

End Class
Step 3 - From the main program then utilize the Client API object to authenticate user and acquire the AccessToken and Expiration (this is a form with user/password/server/API path fields on it and a button
to trigger the operation to be called) on success it simply shows the Access Token and when it expires,
on failure it displays an error message.  Like I said... KEEP THE EXAMPLES SIMPLE, but complete. :)

Private Sub bAuth_Click(sender As Object, e As EventArgs) Handles bAuth.Click
        Dim o As New SmarterMailAPIClient
        Dim res As clsAuthenticateUser = o.DoAuthorizeAndGetAccessToken(tUser.Text,                                                      tPass.Text, tSvr.Text, tAPI.Text)
        If Not IsNothing(res) Then
            With res
                lblAccessToken.Text = .accessToken
                lblExpires.Text = .accessTokenExpiration.ToString("MM/dd/yyyy HH:mm:ss")
            End With
            lblError.Text = "Could not communicate with SmarterMail Server"
        End If
        o = Nothing
End Sub

I sure hope that saves someone the world of headaches I had.

The key to curing the (415) error was one line of code:
myClient.Headers(HttpRequestHeader.ContentType) = "application/json"
Without that the server apparently has no clue how to format what is being sent to it.

Following the methodology above, you should be able to build out any of the operations in the API with .Net's WebClient and the newtonsoft.json library.


1 Reply

Reply to Thread
Ben Gilstrap Replied
Employee Post

Thanks for posting this and for the suggestion!  I've submitted this as a request for you.
Ben Gilstrap
Regional Sales Executive
SmarterTools Inc.
(877) 357-6278

Reply to Thread