Building a Rest API app

by Gisle Hannemyr

Mumble

Table of contents

Introduction

This tutorial provides step by step instructions about transforming a sample Rest API “ToDo”-app on the Xamarin Documentation website into a real app communicating with a Drupal 7 back-end. The source code for the sample app is downloadable from GitHub.

Here are the links to the documentation and the source code:

The sources hosted on Developer.Xamarin and those hosted on GitHub are slightly different:

From the Developer.Xamarin README.md:

This sample demonstrates a Todo list application where the data is stored and accessed from a RESTful web service. The web service is hosted by Xamarin and provides read-only access to the data. Therefore, the operations that create, update, and delete data will not alter the data consumed in the application. However, a hostable version of the REST service that provides read-write access to the data is stored in the TodoRESTService folder.

From the GitHub README.md:

This sample demonstrates a Todo list application where the data is stored and accessed from a RESTful web service. The web service code is in the TodoAPI project.

Differences that don't matter:

Debug existing Xamarin project

  1. Download the source code from GitHub and open the solution in Visual Studio.
  2. Make sure it is the startup project. Startup project are shown using a bold font in Solution Explorer.
  3. Install missing SDK versions. The error message will tell what level API is missing.
  4. Delete the iOS and UWP projects.
  5. Rename the “TodoREST.Droid” to “TodoREST.Android”.

The RestOrl is defined in test.dev/TodoREST/Constants.cs:

namespace TodoREST
{
	public static class Constants
	{
		// URL of REST service
		public static string RestUrl
                    = "https://developer.xamarin.com:8081/api/todoitems/{0}";
		// Credentials that are hard coded into the REST service
		public static string Username = "Xamarin";
		public static string Password = "Pa$$w0rd";
	}
}

Using RESTED to examine endpoint of Xamarin Todo app with Basic auth:

rested02.png
RESTED using Basic auth.

Or retrieved with cURL:

$ curl -u 'username:password' https://developer.xamarin.com:8081/api/todoitems/
[
  {
    "ID":"6bb8a868-dba1-4f1a-93b7-24ebce87e243",
    "Name":"Learn app development",
    "Notes":"Attend Xamarin University",
     "Done":true
  },
  {
    "ID":"b94afb54-a1cb-4313-8af3-b7511551b33b",
    "Name":"Develop apps",
    "Notes":"Use Xamarin Studio/Visual Studio",
    "Done":false
  },
  {
    "ID":"ecfa6f80-3671-4911-aabe-63cc442c1ecf",
    "Name":"Publish apps",
    "Notes":"All app stores",
    "Done":false
  }
]

UUIDs are used for the IDs.

Consuming the Web Service

The REST service is written using ASP.NET Core and provides the following operations:

OperationHTTP methodRelative URIParameters
Get a list of to-do itemsGET/api/todoitems/-
Create a new to-do itemPOST/api/todoitems/A JSON formatted TodoItem
Update a to-do itemPUT/api/todoitems/A JSON formatted TodoItem
Delete a to-do itemDELETE/api/todoitems/{id}-

There are no request to get a single task. All the data for all the tasks are returned by the JSON returned by the GET request.

The CREATE and UPDATE requests comes with a parameter.

Some of the URIs include the object ID in the path. For example, to delete the TodoItem whose ID is 6bb8a868-dba1-4f1a-93b7-24ebce87e243, the client sends a DELETE request to:

http://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243

When the Web API framework receives a request it routes the request to an action. These actions are simply public methods in the TodoItemsController class. The framework uses a routing table to determine which action to invoke in response to a request, which is shown in the following code example:

config.Routes.MapHttpRoute(
    name: "TodoItemsApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { controller="todoitems", id = RouteParameter.Optional }
);

A successful request with no content gets HTTP status code 204 in return.

The routing table contains a route template, and when the Web API framework receives an HTTP request, it tries to match the URI against the route template in the routing table. If a matching route cannot be found the client receives a 404 (not found) error. If a matching route is found, Web API selects the controller and the action as follows:

Final word

[TBA]

Last update: 2019-04-07 [gh].