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 VB.net (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.


8 Replies

Reply to Thread
Employee Replied
Employee Post

Thanks for posting this and for the suggestion!  I've submitted this as a request for you.
I agree and am struggling to get the API to work. While Rod's input here is immensely informative, I still can't get the API to work (I'm not using .NET) even when setting the MIME type. 

We need better documentation all the way around for SM product APIs. That said...it has gotten better of late!
Don't understand how hard it would be to provide the same examples that SM has tested with.
I spending hours because of switching from JSON from SOAP... per the instructions of any new development should be in JSON.

I just created a GitHub repository where we can make community-driven samples until SmarterMail has proper documentation:

I made a working demo that authenticates a user with the AuthenticateUser method, but happy to add additional methods if anyone is interested.

To the SmarterMail team: could you please consider making the API docs available using OpenAPI/Swagger? Please see this example. That would make it a LOT easier to build integrations and generate client libraries (C#, Java, PHP, NodeJS, etc. are all available). :)
Yes. Swagger is amazing, we have 3 products that offer it, makes life amazing. 
Any traction on this ST? Would love to see Swagger implemented. 
I hate to push this again, but having generated client libraries would make life so much easier...
Thank you, very helpful.

Reply to Thread