Lab1 Hello Forge World

(This is a continuation from the previous post: Forge API Intro Labs Overview)

In this lab, we learn the first step into the Forge world and the basic of REST API call. This is a simple Windows Forms application written in C#. The Forge services we use in this lab is POST authenticate, which is a call to obtain a two-legged authentication token required for subsequent calls.

To make REST calls, we use a library called RestSharp. We chose this as the syntax of RestSharp nicely reflects the semantics of REST call and makes it easy to read the code even if you aren’t writing in C#. Please refer to this post about how to include RestSharp library to your project.

Authenticate – Request

Authenticate generates and returns an access_token, which is used for subsequent service calls.

URL: https://developer.api.autodesk.com/authentication/v1/authenticate

Methods: Post

Required Parameters:

  • client_id
  • client_secret
  • grant_type (= “client_credentials”)
  • scope

Documentation: https://developer.autodesk.com/en/docs/oauth/v2/reference/http/authenticate-POST/

client_id and client_secret — these are obtained from https://developer.autodesk.com/. Sign in from the upper-right corner of the page. You will see a menu “My Apps” (again from the top-right corner). If you haven’t gotten client id and secret, yet, please visit the site and sign up for it. Anybody can sign up. For more detail about how to obtain client id and secret, please refer to this documentation. (Note: when you request for those keys, the form will ask you to fill in Callback URL. We do not use it in our exercise. You can enter any dummy URL value there.)

grant_type — this must be “client_credentials”.

scope — The value of scope depends on what you are trying to do. In our labs, we will need:

scope = “bucket:create bucket:read data:read data:write

This allow us to create a storage container (a.k.a. bucket) and to upload a model file for viewing in later labs.

Authenticate – Response

The response to Forge API web services requests are in JSON format. A successful response to the authenticate request looks like below:

{

“token_type”:”Bearer”,

“expires_in”:3599,

access_token“:”cPJ8IbjU4KgDj8tWkuQFjo4hzs8AN…”

}

Note: line breaks are added for readability.

Authenticate – Sample Code

Here is a simple code to show the basic flow of authenticate request. Basically, what we are doing is to (1) fill out the information necessary to send a request, (2) make a web request, and (3) parse the response to get the access token:

Authenticate

        public static string Authenticate(string scope)
        {
            // (1) Build request
            var client = new RestClient();
            client.BaseUrl = new System.Uri(baseApiUrl);

            // Set resource/end point
            var request = new RestRequest();
            request.Resource = “authentication/v1/authenticate”;
            request.Method = Method.POST;

            // Set required parameters
            request.AddParameter(“client_id”, clientID);   
            request.AddParameter(“client_secret”, clientSecret);  
            request.AddParameter(“grant_type”, “client_credentials”);
            request.AddParameter(“scope”, scope);

            // (2) Execute request and get response
            IRestResponse response = client.Execute(request);

            // Save response. This is to see the response for our learning.
            m_lastResponse = response;

            // (3) Parse the response and get the access token.
            string accessToken = “”;
            if (response.StatusCode == HttpStatusCode.OK)
            {
                JsonDeserializer deserial = new JsonDeserializer();
                AuthenticateResponse loginResponse =
                    deserial.Deserialize<AuthenticateResponse>(response);
                accessToken = loginResponse.access_token;
            }

            return accessToken;
        }

Now, let’s take a look at the code in more detail.

REST Call

To make a client REST call, we first set the base URL:

var client = new RestClient();

client.BaseUrl = new System.Uri(baseApiUrl);

The base API URL is: https://developer.api.autodesk.com/

Typically, we define the base API URL, client ID and secret as constants somewhere else, such as in the App.config file.

Next, set the request resource and method. e.g.,

var request = new RestRequest();

request.Resource = “authentication/v1/authenticate”;

request.Method = Method.POST;

Required parameters are set using AddParameter() method, e.g.,

request.AddParameter(“client_id”, clientID);

Finally, call client.Execute(request) to get the response from the web service:

IRestResponse response = client.Execute(request);

Once you get a response, you can check the status of the response. If the status code indicates the success (i.e., OK), obtain header and response body info:

if (response.StatusCode == HttpStatusCode.OK) …

Parse Response

To parse the response, you can use JsonDeserializer class:

JsonDeserializer deserial = new JsonDeserializer();

AuthenticateResponse loginResponse =

deserial.Deserialize<AuthenticateResponse>(response);

accessToken = loginResponse.access_token;

where AuthenticateResponse is defined as:

AuthenticateResponse
    public class AuthenticateResponse 
    {
        public string token_type { get; set; }
        public string expires_in { get; set; } // expiry time in seconds(60 min)
        public string access_token { get; set; }
    }

These are the basic code that you need to make a Forge API call.

Putting Together

Add UI to display an access token that we receive as a result of calling the above Authenticate() function. (A simple Win Form will serve our purpose for this.) As an example, your buttonToken_Click() might look something like this:

buttonLogin_Click

        private static string m_accessToken = “”;

        private void buttonToken_Click(object sender, EventArgs e)
        {
            string scope = “bucket:create bucket:read data:write”;
            // Here is the main part that we call Forge authenticate
            m_accessToken = Forge.Authenticate(scope);

            // Show it in the form
            textBoxToken.Text = m_accessToken;
        }

Disclaimer: as our goal is to learn Forge API, we are not going into the detail of how to build UI, such as adding a button and text fields. You may choose not to add any UI to simplify your testing.

The image below shows a sample UI. (Note: In this sample, we added additional text fields, Request and Response, to show http request and response. Displaying token and request/response is purely for learning purpose and optional for your exercise. In your real application, you won’t show them to the user.)

ForgeIntroLab1

When the authenticate call succeeds, you should receive access_token as a part of response. You will be using the access_token for subsequent calls to the Forge API. You are ready for the next steps: a series of REST calls to upload a model for viewing.

You can get the source code for Lab1 from here: Lab1

For more information about authentication, please refer to my previous posts:

Next: Lab2 “Forge API Intro”

Mikako

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s