(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.
- https://bim360field.autodesk.com/api/login (for U.S.)
- https://bim360field.eu.autodesk.com/api/login (for Europe)
Supported Request Methods: Post
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:
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:
Now, let’s take a look at the code in more detail.
To make a client REST call, we first set the base URL:
client.BaseUrl = new System.Uri(_baseUrl);
The base URL is:
- https://bim360field.autodesk.com for U.S.
- https://bim360field.eu.autodesk.com for Europe. (Please take a look at this post if you aren’t sure which region.)
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.,
request.Resource = “/api/login”;
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:
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:
To parse the response, you can use JsonDeserializer class:
LoginResponse loginResponse =
ticket = loginResponse.ticket;
where LoginResponse is defined as:
These are the basic code that you need to make a Field API call.
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:
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.)
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”