(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.
- grant_type (= “client_credentials”)
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:
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:
Now, let’s take a look at the code in more detail.
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.,
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) …
To parse the response, you can use JsonDeserializer class:
JsonDeserializer deserial = new JsonDeserializer();
AuthenticateResponse loginResponse =
accessToken = loginResponse.access_token;
where AuthenticateResponse is defined as:
These are the basic code that you need to make a Forge API call.
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:
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.)
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:
- Forge Authentication API
- 2-legged Authentication Using Postman
- 3-legged Authentication Using Postman
- Scopes: Values and Viewer Security