Lab2 Glue API Intro

(This is a continuation from the previous post: Lab1 “Hello Glue World”)

In Lab1, we learned how to sign into the Glue using API, and we got familiarized ourselves with the basics of REST call. Let’s move on, and try to retrieve a model and to display it in an embedded viewer.

To achieve this, we use following services:

  • Security/login (same as in the Lab 1)
  • Project list
  • Model list
  • Display component (or viewer)

Work Flow 

The work flow of our little app is as follows:

  • Login – we first log in to the Glue and obtains the auth_token. We learned how to do this in the Lab1.
  • Get a list of projects – we obtain a list of currently available projects. We keep one arbitrary project id (project_id) to further get a model.
  • Get a list of models – from the given project, we obtain a list of models. We keep one arbitrary model id (model_id) to further take action to view in the viewert.
  • Display a model – we use the display component API to display a model.

As an example, the application may look something like the following:

2015_0113_Lab2GlueIntro_UI

Request and Response added for learning purpose.

 

Project List – Request

Project/List returns a list of projects from the Glue platform.

URL: https://b4.autodesk.com/api/project/v1/list.{format}

Supported Request Methods: GET

Required Parameters:

  • format
  • company_id
  • api_key
  • timestamp
  • signature (sig)
  • auth_token (obtained from login)

Doc: https://b4.autodesk.com/api/project/v1/list/doc

We are using JSON as format. The next five parameters are always needed for any subsequent requests. Note that auth_token is the one we received through the earlier Login request.

Project List – Response

Here is the sample response for Project/List:

{
“project_list”:
[
{
“folder_tree”:null,
“project_roster”:null,
“project_id”:”The BIM 360 Glue Project ID”,
      “project_name”:”The name for the project (URL Encoded)”,
“company_id”:”The Company ID for the Project”,
“created_date”:”The date the Project was added”,
“modify_date”:”The date the Project name was last modified”,
“start_date”:”The date the Project was started”,
“end_date”:”The date the Project ends”,
“last_activity_date”:”The last date there was Project activity”
},
{
“folder_tree”:null,
“project_roster”:null,
“project_id”:”The BIM 360 Glue Project ID”,
. . .
}
],
“page”:1,
“page_size”:2,
“total_result_size”:2,
“more_pages”:0
}

For our specific little app, we’ll be interested in project_id and project_name.

Project List – Sample Code

Here is the code sample to obtain a list of project:

ProjectList

    public List<Project> ProjectList(string authToken)
    {
       string timeStamp = Utils.GetUNIXEpochTimestamp().ToString();
       string signature = Utils.ComputeMD5Hash(apiKey + apiSecret + timeStamp);

       // (1) Build request
       // set base url and authentication info.
       var client = new RestClient();
       client.BaseUrl = baseApiUrl;

       // Set resource or end point
       var request = new RestRequest();
       request.Resource = “project/v1/list.json”;
       request.Method = Method.GET;

       // Add parameters
       request.AddParameter(“company_id”, companyId);
       request.AddParameter(“api_key”, apiKey);
       request.AddParameter(“timestamp”, timeStamp);
       request.AddParameter(“sig”, signature);
       request.AddParameter(“auth_token”, authToken);

       // (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;

       if (response.StatusCode != HttpStatusCode.OK)
       {
          returnnull;
       }

       // Get a list of projects.
       JsonDeserializer deserial = new JsonDeserializer();
       ProjectListResponse projListResponse =
           deserial.Deserialize<ProjectListResponse>(response);
       List<Project> proj_list = projListResponse.project_list;

       return proj_list;
    }

Careful reader may already see some “pattern” here; there are many parts of the code that are more or less the same as in our previous experience with Login REST call. In this example, we return a list of projects. You could easily modify that part to fit your needs, of course.

Once you obtained a list of projects (proj_list), you can access project id and its name of a specific project as follows:

  Project proj = proj_list[index];
string project_id = proj.project_id;
  string project_name = proj.project_name;

ProjectListResponse is defined as follows:

ProjectListResponse

  public class ProjectListResponse
  {
    public List<Project> project_list { get; set; }

    // General Description of result set
    public int page { get; set; }
    public int page_size { get; set; }
    public int total_result_size { get; set; }
    public int more_pages { get; set; }

    // Add the list of project info if needed
  }

  public class Project
  {
     public string project_id { get; set; }
     public string project_name { get; set; }
     public string company_id { get; set; }
     public string created_date { get; set; }
     public string modify_date { get; set; }
     public string modify_user { get; set; }
     public string start_date { get; set; }
     public string end_date { get; set; }
     public string thumbnail_modified_date { get; set; }
     public string has_views { get; set; }
     public string has_markups { get; set; }
     public string has_clashes { get; set; }
     public string last_activity_date { get; set; }
  }

(Note: I’m only taking data types, string and int, here for simplicity. You can add other data types as your programs require them.)

Let’s go to the Model/List request next.

Model List – Request

Model/List returns a list of models within a given project from the Glue platform.

URL: https://b4.autodesk.com/api/model/v1/list.{format}

Supported Request Methods: GET

Required Parameters:

  • format
  • company_id
  • api_key
  • timestamp
  • signature (sig)
  • auth_token (obtained from login)
  • project_id (obtained from the previous call)

Doc: https://b4.autodesk.com/api/model/v1/list/doc

Model List – Response

Here is an example of Model/List response:

{
“model_list”:
[
{
“company_id”:”The company identifier for this model”,
“project_id”:”The Project identifier for this model”,
“model_id”:”The model identifier for the model”,
“model_version”:1,
“model_version_id”:”The version identifier for this specific version of the model”,
“model_name”:”The name for the model”,
“created_by”:”The login_name of the creator of the model”,
“created_date”:”The date of model was created”,
“modified_by”:”The login_name of the last user to modify the model”,
“modified_date”:”Date of last modification”,
. . .
“published”:0
},
{
“company_id”:”The company identifier for this model”,

}
],
“page”:1,
“page_size”:2,
“total_result_size”:2,
“more_pages”:0
}

For our app, we are interested in model_id and model_name.

Model List – Sample Code

Here is the code sample to obtain a list of project:

ModelList

    public List<ModelInfo> ModelList(string authToken, string projectId)
    {
       string timeStamp = Utils.GetUNIXEpochTimestamp().ToString();
       string signature = Utils.ComputeMD5Hash(apiKey + apiSecret + timeStamp);

       // (1) Build request
       // set base url and authenticatopm info.
       var client = new RestClient();
       client.BaseUrl = baseApiUrl;

       // Set resource or end point
       var request = new RestRequest();
       request.Resource = “model/v1/list.json”;
       request.Method = Method.GET;

       // Add parameters
       request.AddParameter(“company_id”, companyId);
       request.AddParameter(“api_key”, apiKey);
       request.AddParameter(“timestamp”, timeStamp);
       request.AddParameter(“sig”, signature);
       request.AddParameter(“auth_token”, authToken);

       request.AddParameter(“project_id”, projectId);

       // (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;

       if (response.StatusCode != HttpStatusCode.OK)
       {
          returnnull;
       }

       // Get a list of models.
       JsonDeserializer deserial = new JsonDeserializer();
       ModelListResponse modelListResponse =
           deserial.Deserialize<ModelListResponse>(response);
       List<ModelInfo> model_list = modelListResponse.model_list;

       return model_list;
    }

where ModelListResponse is defined as follows:

ModelListResponse

  public class ModelListResponse
  {
    // The user list for the project
    public List<ModelInfo> model_list { get; set;}     
     
    // General Description of result set
    public int page { get; set; }
    public int page_size { get; set; }
    public int total_result_size { get; set; }
    public int more_pages { get; set; }
  }

  public class ModelInfo
  {
    public string company_id { get; set; }
    public string project_id { get; set; }
    public string model_id { get; set; }
    public int model_version { get; set; }
    public string model_version_id { get; set; }
    public string model_name { get; set; }
    public string created_by { get; set; }
    public string created_date { get; set; }
    public string modified_by { get; set; }
    public string modified_date { get; set; }
    public string parent_folder_id { get; set; }
    public int file_parsed_status { get; set; }

    // Other General Info
    public int is_merged_model { get; set; }
    public int is_folder { get; set; }
    public int is_deleted { get; set; }
    public int metadata_version { get; set; }
    public string file_units { get; set; }
    public int published { get; set; }

    // Add other info if needed
  }

(Note: once again, I’m only taking data types, string and int, here for simplicity.)

By now, I hope you see the pattern to make REST call and starting to feel comfortable with a big picture of REST API.

Add UI’s to get a project and a model id. For example, add a button to call ProjectList(). Choose a project; an arbitrary project, such as the first one in the list is enough for this exercise. In the simplest form, the code to get a project might look like this:

buttonProjects_Click

    private static string m_project_id = “”;

    private void buttonProjects_Click(object sender, EventArgs e)
    {
      List<Project> proj_list = glueCall.ProjectList(m_authToken);

      // We want to get hold of one project.
      // For simplicity, just pick up arbitrary one.
      Project proj = proj_list[0];
      m_project_id = proj.project_id;
      string project_name = proj.project_name;
    }

Similarly, add another button to call ModelList() and choose a model.

In our sample project, we simply start from the index zero (0), and every time a user press Project or Model button, increments index.) We need a project id and a model id to view it in a viewer.

A little disclaimer: once again, our focus is on how to use Glue API. We assume the reader has the basic familiarity of Visual Studio environment. We will not go into too much detail on how to build the UI. Feel free to tweak the code for your testing need.

Next, we will add a viewer to our little app and display a model.

Viewer

The display component, or viewer API, allows users to place a Glue 3D model on a web page.

URL: https://b2.autodesk.com?

Required Parameters: 5 usual required parameters, plus two ways:

  • “&runner=embedded/#” + company_id + ”/”+ project_id + ”/” + model_id
  • “&runner=embedded/#” + company_id + “/action” + “/” + action_id

Doc: https://b4.autodesk.com/api/doc/doc_disp_comp.shtml

Warning: as of this writing, the above page is not up to date. But it still includes useful information about the idea of viewer.

Response for the viewer is, of course, is graphics, which looks something like the image shown at the beginning of this post.

Viewer – Sample Code

Here is a sample code:

View

    public string View(string authToken, string projectId, string modelId)
    {
      string timeStamp = Utils.GetUNIXEpochTimestamp().ToString();
      string signature = Utils.ComputeMD5Hash(apiKey + apiSecret + timeStamp);

      string callArgs = “”;
      // We need these 5 arguments for every subsequent requests.
      // Auth token is returned when you login.
      callArgs += “&company_id=” + HttpUtility.UrlEncode(companyId);
      callArgs += “&api_key=” + HttpUtility.UrlEncode(apiKey);
      callArgs += “&timestamp=” + HttpUtility.UrlEncode(timeStamp);
      callArgs += “&sig=” + HttpUtility.UrlEncode(signature);
      callArgs += “&auth_token=” + HttpUtility.UrlEncode(authToken);

      // Two ways to pass parameters.
      // (1) “&runner=embedded/#” + company_id + ”/”+ project_id + ”/” + model_id
      // (2) “&runner=embedded/#” + company_id + “/action” + “/” + action_id
      // We use #1 here with the saved project and model ids.

      callArgs += “&runner=embedded/#” + HttpUtility.UrlEncode(companyId)
        + “/” + projectId + “/” + modelId;

      // URL that we are going to embed a web browser.
      string url = baseViewerUrl + callArgs;

      return url;
    }

Add UI’s to call View() shown above with the project and the model id obtained in previous steps. e.g.,

  string url =
glueCall.View(m_authToken, m_project_id, m_model_id);

  // a view embedded form’s web browser by URL.
  webBrowser1.Url = new System.Uri(url);

If you pass the url to the web browser, you should be able to view a model. As an experiment, try copy and pasting the url directly in the address box of your Chrome or Firefox, and see what happens. (Troubleshooting Tip: Copy and pasting the composed url to a browser directly is one way to test and troubleshoot when something is not working with the viewer.)

Warning: the viewer component provides JavaScript layer, which may throw script error messages in the environment like win form. To avoid the message, set ScriptErrorsSuppressed as True in the properties of WebBrowser tool. As this shows, Glue display component is meant to be used as a web service, and not designed to be used as embedded in a win forms application. We are doing this as a way of learning.

You can download the full code project for the Glue API Intro Labs from the earlier post or directly from here.

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s