Generate client in Visual Studio for SmartConnector RESTful Endpoints

[JeffBowman]

When consuming the SmartConnector RESTful Endpoints, it is always necessary (or at least incredibly helpful and time saving) to have a Client. Luckily because SmartConnector REST leverages swagger, these clients can be autogenerated for you! This generated client contains all the interfaces and classes needed to extend it as well as all the Models needs to send requests, and receive deserialized responses.

Follow the steps below:

1. Navigate to your swagger page and then copy and paste the URL that contains the actually swagger DOC should look something like: "http://10.169.86.198:8083/SBO/swagger/docs/v1

2. Go to file >>save, and save as a .json file

3. In Visual studio, in your project go to Add >REST Api Client. Select the "Select an existing Swagger metadata file" and browse to your file and select OK. If you do not see this option, make sure you have installed the Azure SDK on your VS installation.

4. You should see a new Folder in your project that contains all the interfaces and classes needed to use this client. The client class name should be the name of your Endpoint (in my case it is SboRestEndpoint).

The ONLY thing that this autogenerated client does NOT have, is the ability to get a BearerToken(for some reason this endpoint isn't exposed from Swagger) but this can be done pretty simply using the BeaerToken class in Mongoose.Common.Security, see below:

var token = BearerToken.ObtainToken(BaseUri, Username, Password, "GetToken");

5. Initialize your client. An example on how to initialize your client is seen below:

            var token = BearerToken.ObtainToken(baseUri, username, password, "GetToken");
            var credentials = new TokenCredentials(null, token.access_token);
            var client = new SBORestEndpoint {Credentials = credentials, BaseUri = baseUri};
            client.Credentials?.InitializeServiceClient(client);

6. Use your client (examples below)

            var rootResponse = client.Root.RetrieveWithOperationResponseAsync();
            var sboEwsId = "01/Server 1/MyValueItem";
            var valueResponse = client.Values.RetrieveByIdWithOperationResponseAsync(sboEwsId.UrlEncodeToString());

One helpful thing to note is that certain requests, the ones that you can add custom string in a URL (generally the {id} in the request URLs), those parameters need to be DOUBLE encoded for some reason (the autogenerated client, single encodes by default).. I wrote an extension method for this (see below, you will notice it was used above):

        #region UrlEncodeToString
        public static string UrlEncodeToString(this string stringToEncode)
        {
            if(string.IsNullOrEmpty(stringToEncode))
            {
                return null;
            }
            else
            {
                return HttpUtility.UrlEncode(stringToEncode.Replace(" ", "~")).Replace("%7e", " ");
            }
        }
        #endregion

If you need anymore examples using the AutoGenerated client, please let me know.

Also, if interested in using a different programming language for the client, the same program that Visual Studio uses to create the Client, can be used as a command line tool to create clients in other languages, see link: GitHub - Azure/autorest: Swagger (OpenAPI) Specification code generator featuring C# and Razor templ...

-Jeff

[JeffBowman]

NOTE: There is a current bug when using the BearerToken.ObtainToken() method. It only works with the username 'admin'. A patch for this will be released along with the 'offical' documentation. If you need the fixes sooner than that, we can post to the CTP feed. Just let us know!

As of SmartConnector 2.2.124 (now up on SmartConnectorServer), this issue has been resolved!

[SteveGregory]

Hi Jeffrey, this is really helpful. Is this information available as a document that we can issue to third party developers?

[sesa180908_brid]

Steve,

There really is no notion of "third party developer", there is only a registered SmartConnector Developer.  All known issues are published with each release and are available to all SmartConnector Developers.

As issues are discovered between releases, we will update the last version of the release notes accordingly.

[SteveGregory]

Sorry my reply was intended for initial post, and the comment was around having a similar one page 'cheat sheet' on how to quickly integrate to our SmartConnector, that we can give to third party developers. 

[JeffBowman]

Hi Steven,

We have no official documentation for this except for this post. But in theory, we could create a PDF from it if that works, or you could just copy it if you wanted as well.

An issue that you would most likely encounter for a third party (non SmartConnector developer) is that they won't have access to the BearerToken.ObtainToken() method, as they won't have access to the SmartConnector Nuget packages. So they would need to write their own method for this.

Basically they will need to post to the Token endpoint with a body like the below.

grant_type=password&username=myusername&password=mypassword

We are most likely going to abstract out this method, so that anyone can use it. But for now, they will need to roll their own.

Regards,

-Jeff

[sesa180908_brid]

Steve,

We'll look into providing some public facing artifacts, be it just documentation or perhaps a public NuGet which already has the proxy classes. 

[sesa180908_brid]

Steve,

I updated the samples repo on GitHub to include a REST client based on Jeff's original post.  See GitHub - BuildingsLabs/SmartConnectorSamples: Sample projects for SmartConnector It has some additional feautres around re-authenticating if the token has expired and so on.  Since this is public, it can be shared with outside consumers.

We'll probably add more over time, but it is certainly a good place to start.

[sesa237670_brid]

"In Visual studio, in your project go to Add >REST Api Client. Select the "Select an existing Swagger metadata file" and browse to your file and select OK."

Does this work with Visual Studio 2017 ? I am using VS2015 and don't see the option to add Rest Api client in my project.

[JeffBowman]

Hi Neeraj,

I am not 100% sure if it is in VS2015 or not, but i definitely recommend updating to VS2017.

That said, the application used for creating the client 'AutoRest' is actually a command line tool, so you can actually just do it manually. See the link in the blog post for more information about that.

Regards,

-Jeff