Lab1 Hello Field World

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

In this lab, we learn the first step into the Field API world and the basic of REST API call. This is a simple Windows Forms application written C#. The Field API service we use in this lab is api/login, which is a call to sign to the Field and obtain an authentication token or ticket, which is used 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.

Login – Request

Login authenticates a user to the Field platform and returns an authentication token (ticket), which is used for subsequent service calls.

URL: https://bim360field.autodesk.com/api/login

Supported Request Methods: Post

Required Parameters:

  • username
  • password

Documentation: https://bim360field.autodesk.com/apidoc/index.html#mobile_api_method_1

username and password are the same as Autodesk ID and should be provided by the user.

Note: at the time of this writing, the use of API for Field does not require API keys. Once you have an access to the product, you are ready to use API.

Login – Response

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

{

“ticket”:”a66f24f8-e78c-4125-a7f2-9f7e06a1484b”,

“message”:””,

“title”:””

}

Note: line breaks are added for readability.

Login – Sample Code

Here is a simple code to show the basic flow of login 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:

Login

        public static string Login(string userName, string password)
        {
            // (1) Build request
            var client = new RestClient();
            client.BaseUrl = new System.Uri(_baseUrl);

            // Set resource/end point
            var request = new RestRequest();
            request.Resource = “/api/login”;
            request.Method = Method.POST;

            // Set required parameters
            request.AddParameter(“username”, userName);
            request.AddParameter(“password”, password);

            // (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 ticket.
            string ticket = “”;
            if (response.StatusCode == HttpStatusCode.OK)
            {
                JsonDeserializer deserial = new JsonDeserializer();
                LoginResponse loginResponse =
                    deserial.Deserialize<LoginResponse>(response);
                ticket = loginResponse.ticket;
            }

            return ticket;
        }

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(_baseUrl);

The base URL is: https://bim360field.autodesk.com

Typically, we define the base URL as constants somewhere else, such as in the config file.

Next, set the request resource and method either Post or Get. e.g.,

    var request = new RestRequest();
    request.Resource = “/api/login”;
    request.Method = Method.POST;

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

    request.AddParameter(“username”, userName);

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();
    LoginResponse loginResponse =
        deserial.Deserialize<LoginResponse>(response);
    ticket = loginResponse.ticket;

where LoginResponse is defined as:

LoginResponse
    public class LoginResponse
    {
        public string ticket;
        public string message;
        public string title;
    }

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

Putting Together

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

buttonLogin_Click

        privatestaticstring m_ticket = “”;

        privatevoid buttonLogin_Click(object sender, EventArgs e)
        {
            // Get the user name and password from the user.
            string userName = textBoxUserName.Text;
            string password = textBoxPassword.Text;

            // Here is the main part that we call Glue login
            m_ticket = Field.Login(userName, password);
        }

A little disclaimer here: as our goal is to learn Field API, we are not going into too much detail of how to build UI, such as adding a button and text fields. Doing so blurs the main focus of this instruction. You may choose to hard-code without any UI if you are simply testing Field API calls at this point.
The image below shows a sample UI. (Note: In this example, we added additional text fields, Request and Response, to show http request and response. This is for learning purpose and optional for your exercise. In your real application, you probably do not show these to the user.)

20150408_FieldApiIntro

When the authenticate call succeeds, you should receive ticket as a part of response. You will be using the ticket for subsequent calls to the Field API. You are ready for the next lab to request a list of projects.

You can download the Field API Intro Labs code from here.

Next: Lab2 “Field 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 )

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