What Is a RESTful API?

In its simplest form, a RESTful API is a way for clients to request data using a web URL (Uniform Resource Locator) and the request can be given a response in a known format from the server. The client can use HTTP verbs like GET, PUT, and DELETE to perform actions on the data. This matches up with typical CRUD (Create, Read, Update and Delete) operations like getting leaderboard data, saving or replacing player state, and deleting a save slot, for example. This means that the client does not have to be written in the same language as the server. Because the requests use URLs and standard HTTP messages, there is no need to open additional ports. The developer just needs to be able to request a web page to read or write information.

REST is short for REpresentational State Transfer . API is short for Application Programming Interface . As long as the client and the server agree on the messages – the format of the requests and their responses – and how those requests are made using HTTP, both the client and the server will understand the messages passed between them.

As shown in Figure 3-2, a request is made to a website using a RESTful call. The response that returns is a JSON string.

The UnityWebRequest Class

Reading and writing data to a remote website is made possible through the UnityWebRequest class . You do not create a UnityWebRequest class directly. Instead you use the Get() method and pass in the URL of the RESTful API endpoint.

The UnityWebRequest class is typically used in a co-routine because of its asynchronous nature. A request is made and at some point in the future that request is given a response.

A normal function in Unity must execute completely before anything else can complete. If there is a function that takes a long time, this will affect the performance of your game. To combat this, Unity created co-routines. These are functions that yield control back to Unity when they need to wait longer than a frame to complete. When the function is called again, it picks up where it left off. See https://docs.unity3d.com/Manual/Coroutines.html for more details.

Errors are handled by checking the isNetworkError and isHttpError properties once the request operation has completed. The text of the error is contained in the error property of the request instance.

The response is located in the text property of the web request’s downloadHandler. This is just C# code and no further processing is required. The response will usually be in the JSON format, so creating classes from it is a simple matter of using JsonUtility.FromJson<T>().

Fetching Text

Listing 3-1 illustrates how to fetch a web page. For this example, it’s the Google home page. The script can be attached to a game object like the Main Camera in a blank project and run.

using System.Collections;

using UnityEngine;

using UnityEngine.Networking;

public class FetchGoogle : MonoBehaviour

{

    IEnumerator Start()

    {

        UnityWebRequest request = UnityWebRequest.Get("https://www.google.com/");

        yield return request.SendWebRequest();

        if (request.result == UnityWebRequest.Result.Success)

        {

            Debug.Log(request.downloadHandler.text);

        }

        else

        {

            Debug.Log(request.error);

        }

    }

}

Listing 3-1

Fetch the Google Home Page from the Web Using UnityWebRequest

The Start() method is a co-routine that will not stall out the game while the web request is waiting for a response. The SendWebRequest() method returns an enumerator that exits when either an error occurs or when the data has been received.

If an error occurs in this example, it is printed to the console. If data is returned it is printed to the console, as shown in Figure 3-3. This is the HTML of the Google home page—the one with the search box in the middle of the screen.

Note

A request is required for each resource. If you were building a web server, you would have to make several requests for the HTML page, each image, each stylesheet, and each JavaScript file needed to display the page completely.

Fetching Images

The UnityWebRequest class can be used to return an image. The following example fetches the Unity Logo from Wikimedia Commons, as shown in Figure 3-4.

Creating the Project

Create the project by completing the following steps:

1. 1.

   Create a new 2D project from Unity Hub named Fetch Example.

    
2. 2.

   Add an empty GameObject to the scene called Logo.

    
3. 3.

   Add a SpriteRenderer component to the Logo GameObject.

    
4. 4.

   Create a new folder in Assets called Scripts.

    
5. 5.

   Inside the Scripts folder, create a C# script called FetchLogo.

    
6. 6.

   Attach the FetchLogo script to Logo using the Add Component button or by dragging the script onto Logo.

    

The GameObject’s component list should look like the one shown in Figure 3-5. Save the scene.

Fetching the Image

The UnityWebRequest class is part of a group of classes that are used to download data from remote websites. To download an image, use the UnityWebRequestTexture class.

Open the FetchLogo script and change the script to look like Listing 3-2.

using System.Collections;

using UnityEngine;

using UnityEngine.Networking;

public class FetchLogo : MonoBehaviour

{

    IEnumerator Start()

    {

        string url = "https://upload.wikimedia.org/wikipedia/commons/8/8a/Official_unity_logo.png";

        var request = UnityWebRequestTexture.GetTexture(url);

        yield return request.SendWebRequest();

        if (request.result == UnityWebRequest.Result.Success)

        {

            var textureHandler = request.downloadHandler as DownloadHandlerTexture;

            Texture2D texture = textureHandler.texture;

            SpriteRenderer = GetComponent<SpriteRenderer>();

            var rect = new Rect(0, 0, texture.width, texture.height);

            spriteRenderer.sprite = Sprite.Create(texture, rect, Vector2.zero);

        }

        else

        {

            Debug.Log(request.error);

        }

    }

}

Listing 3-2

Fetching an Image from a Website Using UnityWebRequestTexture

Instead of using the Get() method, as you did for the text, the GetTexture() method is used. This returns an instance of UnityWebRequestTexture, but, the actual return is an object of type UnityWebRequest. You must do some casting to get the objects back to the type that you need in order to get the texture.

The download handler that is returned from a UnityWebRequest is a standard DownloadHandler instance. However, after casting the UnityWebRequestTexture’s downloadHandler property to the DownloadHandlerTexture class, we can access the downloadHandler’s texture property.

Then it is a simple matter of creating a Sprite object and passing the downloaded texture. When run, the image is downloaded and the sprite is constructed, as shown in Figure 3-6.

Fetching Other Types

Other resources can be downloaded from websites by using the appropriate UnityWebRequest class and the associated DownloadHandler :

• Audio – UnityWebRequestMultimedia/DownloadHandlerAudioClip

• Asset Bundle – UnityWebRequestAssetBundle/DownloadHandlerAssetBundle

• Text – UnityWebRequest/DownloadHandler

• Textures – UnityWebRequestTexture/DownloadHandlerTexture

Asset bundles can group assets together. Typical uses include texture packs and downloadable content (DLC).

The Weather Application

In this chapter, you are going to build a functioning application that uses data provided by a remote site. Access to the data is through a RESTful API and requires a token.

The OpenWeather project provides accurate weather forecasting data and has an API with which to build your own applications. The website, shown in Figure 3-7, is located at https://openweathermap.org/.

Registering and Getting an API Key

Before you start, you need to obtain an API key. This key will be used in all your queries. To obtain a key, you must first get an account with the site. To do that, locate the Sign In menu option along the top of the page and click the Create an Account link. This will take you to the sign-up page, as shown in Figure 3-8.

Once completed, you will get a confirmation message sent to the email account that you provided. Do not forget to verify your email address!

Note

It can take upwards of two hours to get a confirmation back while OpenWeather creates a valid key.

Once logged in, you will be taken to your account home page. Click the API Keys link shown in Figure 3-9.

By default, an API key is defined for you with the name default. You can edit this to be any name you like: for example, the name of your application. The most important part, though, is the key itself. This is what will be used to verify your application when you make a call to an API. Figure 3-10 shows my API key that I have renamed to Unity Net Book. The name is more of a mnemonic for you and is not required when making an API call.

Note

Each new application requires a different API key.

The User Interface

The application’s user interface, shown in Figure 3-11, includes a text box to allow users to enter their city and country, a button to fetch data, and a button to toggle between Celsius and Fahrenheit.

The resources for this project can be obtained by clicking the Download Source Code button located at www.apress.com/9781484273579. This includes the images for the weather icons, the prefabs for each day, and the fonts.

Creating the Project

Follow these instructions to create the basic WeatherApp project :

1. 1.

   Create a new blank 2D project in Unity Hub named weather-app.

    
2. 2.

   Import the weather-application.unitypackage from the resources folder on the GitHub repo to get the prefabs, images, fonts, and starting scene.

    

Importing the weather-application.unitypackage

In the Unity editor, choose Assets ➤ Import Package ➤ Custom Package from the main menu. In the Import Package dialog box, locate the weather-application.unitypackage and open it. Figure 3-12 shows the contents of the package. These files will be added to the blank project. Click Import at the bottom-right side of the dialog to add the files to your project.

Fetching the Data

With the barebones project imported via the package, you need to create additional scripts that will:

• Provide classes to decode the JSON message received from the API call

• Use a common function to make the call to the API

• Send out the request when the user clicks the Fetch button

Let’s start by creating the script files you need. In the Unity Editor’s Project view, open the Scripts folder and add the following C# script files:

• FetchResults

• OpenWeatherMapAPI

Then create a new folder in Scripts called Serialization. Create the following C# script files inside the Serialization folder :

• ResponseContainer

• ResponseItem

• ResponseTemperature

• WeatherItem

The last four C# script files will hold the response from the server. You should now have a project that looks like the hierarchy shown in Figure 3-13.

Serialization Classes

The serialization classes in Scripts/Serialization will just be plain classes with public fields that will be populated with data.

Note

Unity’s JsonUtility can only serialize/deserialize public fields. Do not use properties for your serialization classes!

The shape of the data (i.e. the names of the fields and the class structure) is dictated by the application. In the case of the daily forecast from OpenWeather, this is defined at https://openweathermap.org/forecast16#JSON and a portion of it is shown in Figure 3-14.

The date (dt), sunrise, and sunset fields are 10 digits long. These values are the number of seconds since midnight on 1/1/1970. You’ll learn how to create a function to convert them to something human readable later in the UnixTimeToDateTime() function .

Taking this hierarchy, you can draw a diagram to represent the parent-child relationships of each class as shown in Figure 3-15.

The ResponseContainer is the message received from the server. Each ResponseItem is a day of the week.

The leaf node in this hierarchy is what I called the WeatherItem and it is defined in Listing 3-3.

using System;

[Serializable]

public class WeatherItem

{

    public int id;

    public string main;

    public string description;

    public string icon;

}

Listing 3-3

The WeatherItem Script

This class contains the icon used to visually represent the weather as well as a description of the weather itself. Paired with the WeatherItem class is the ResponseTemperature class, shown in Listing 3-4. It contains, unsurprisingly, the temperature for the parts of the day. The temperatures returned from the API are in Kelvin. You will write a function called ToHumanTemperature() that will convert the temperature from Kelvin to Celsius or Fahrenheit.

Note

Zero Kelvin is approximately -273 Celsius or -460 Fahrenheit!

using System;

[Serializable]

public class ResponseTemperature

{

    public float day;

    public float night;

    public float min;

    public float max;

    public float eve;

    public float morn;

}

Listing 3-4

The ResponseTemperature Script

Daily temperatures, icons, and descriptions are contained in the ResponseItem class , as shown in Listing 3-5. This represents a single day’s results in addition to the sunrise and sunset times for that day.

using System;

[Serializable]

public class ResponseItem

{

    public long dt;

    public ResponseTemperature temp;

    public WeatherItem[] weather;

    public long sunrise;

    public long sunset;

}

Listing 3-5

The ResponseItem Script

The dt, sunrise, and sunset fields are not in the DateTime format. This is because the OpenWeatherMap API returns times in what is called UNIX Epoch time. This is the number of seconds since midnight on 1/1/1970.

Lastly, the actual message itself is represented in code as ResponseContainer, as shown in Listing 3-6. It contains a collection of ResponseItem instances as well as the count of the number of days requested.

using System;

[Serializable]

public class ResponseContainer

{

    public string cod;

    public float message;

    public int cnt;

    public ResponseItem[] list;

}

Listing 3-6

The ResponseContainer Script

Now that the serializable classes have been defined, you can take a look at creating a MonoBehaviour that queries the OpenWeather endpoint for a particular location and returns the result to the caller.

Calling the API

As in the previous examples, you will use the UnityWebRequest class to fetch the data from the remote server. JsonUtility.FromJson<T>() is used to create the ResponseContainer from the JSON response.

There is one exposed field that is settable through the Unity editor for the API key. You will have to provide that key yourself. The entire class is shown in Listing 3-7.

using System.Collections;

using System.Web;

using UnityEngine;

using UnityEngine.Networking;

public class OpenWeatherMapAPI : MonoBehaviour

{

    private static readonly string ApiBaseUrl = "https://api.openweathermap.org/data/2.5/forecast/daily?q={0}&cnt=5&appid={1}";

    [Tooltip("The key that allows access to the OpenWeatherMap API")]

    public string apiKey;

    public ResponseContainer Response { get; private set; }

    public IEnumerator GetForecast(string city)

    {

        Response = null;

        string urlEncodedCity = HttpUtility.UrlEncode(city);

        string url = string.Format(ApiBaseUrl, urlEncodedCity, apiKey);

        UnityWebRequest webRequest = UnityWebRequest.Get(url);

        yield return webRequest.SendWebRequest();

        if (webRequest.result == UnityWebRequest.Result.Success)

        {

            string json = webRequest.downloadHandler.text;

            Response = JsonUtility.FromJson<ResponseContainer>(json);

        }

        else

        {

            Debug.Log(webRequest.error);

        }

    }

}

Listing 3-7

The OpenWeatherMapAPI MonoBehaviour Script

Notice that the endpoint is stored as a constant called ApiBaseUrl and the string.Format() method is used to place the query and the API key in the query. Also of note is the UrlEncode() method, which is used to encode the query string.

This MonoBehaviour is used by the final script that you write, which acts as a controller for the whole application. If you were writing an application that uses a lot of API calls, it would be rather inefficient to rewrite this over and over again. At the end of this chapter, you’ll take a look at making this more generic.

The Controller: Final Wiring

The controller acts as the glue code between the UI and the API. The script is attached to the FetchButton object in the project hierarchy, shown in Figure 3-16, along with the OpenWeatherMapAPI MonoBehaviour.

The FetchResults class, as shown in Listing 3-8, adds a click event handler to the button to which it is attached. The event handler calls the FetchData() method and that in turn calls the OpenWeatherMapAPI’s GetForecast() method. On a successful response, the day prefabs are filled.

using System.Collections;

using System.Collections.Generic;

using TMPro;

using UnityEngine;

using UnityEngine.UI;

public class FetchResults : MonoBehaviour

{

    private static readonly string DefaultIcon = "01d";

    private bool isRunningQuery;

    private Button;

    private OpenWeatherMapAPI api;

    private Dictionary<string, Sprite> sprites = new Dictionary<string, Sprite>();

    public GameObject loadingMessage;

    public TMP_InputField cityInputField;

    public DayCard[] dayCards;

    public Sprite[] spriteIcons;

    public CanvasGroup panel;

    void Awake()

    {

        button = GetComponent<Button>();

        api = GetComponent<OpenWeatherMapAPI>();

        // Create the dictionary that maps the name of the sprite to its image

        foreach (Sprite s in spriteIcons)

        {

            sprites[s.name] = s;

        }

        button.onClick.AddListener(delegate

        {

            if (!string.IsNullOrEmpty(cityInputField.text.Trim()) && !isRunningQuery)

            {

                StartCoroutine(FetchData(cityInputField.text));

            }

        });

    }

    private IEnumerator FetchData(string query)

    {

        isRunningQuery = true;

        panel.alpha = 0;

        loadingMessage.SetActive(true);

        yield return api.GetForecast(query);

        loadingMessage.SetActive(false);

        isRunningQuery = false;

        if (api.Response != null)

        {

            FillDays(api.Response);

            panel.alpha = 1;

        }

    }

    private void FillDays(ResponseContainer response)

    {

        panel.alpha = 1;

        for (int i = 0; i < dayCards.Length; i++)

        {

            var icon = response.list[i].weather[0].icon;

            if (!sprites.ContainsKey(icon))

            {

                icon = DefaultIcon;

            }

            Sprite = sprites[icon];

            DayCardModel day = new DayCardModel(response.list[i], sprite);

            DayCard = dayCards[i];

            dayCard.SetModel(day);

        }

    }

}

Listing 3-8

The FetchResults MonoBehaviour script

The final thing to do is to enter the API token on the OpenWeatherMapAPI script in the Unity Editor. At this point, you can test the application—everything is complete!

Generic RESTful API Client

As I mentioned earlier, you may find yourself doing multiple calls to various endpoints to build your client. If this is the case, it is better to abstract the remote call out of the class and into a helper class.

The bold code line is the one that performs the API call to get the forecast data. The FillDays() method will be called automatically once the remote call has completed successfully.

Summary

Your game can act as a client to a remote service that exposes various methods using a RESTful interface. This will allow you to perform read and write operations on remote data. These are performed by requesting a particular URL or endpoint.

There are two methods of authentication: one is per user, the other is per application. OAuth requires users to sign in to a service like Google, Twitter, etc. and obtain a token. The alternative is that the application provides the token. The token is then passed via each call to the remote server to validate the request. Out of date or invalid tokens will get rejected.

Results from the remote service are usually returned in a JSON format. Classes can be easily created using the JSON function built into Unity.

If you are making multiple calls to different endpoints, it is a good idea to create a generic function to perform the remote calls.

The weather application uses a high-level client server architecture. It’s now time to switch gears and look at the lower-level socket programming that is provided as part of the .NET framework, as this will allow you to create your own protocols.