Custom API in Azure Mobile Services – Client SDKs

Article
06/18/2013

In the last post I talked about the new custom API support in Azure Mobile Services. In that post I focused on the feature at the server side, but we also released updates to the client SDKs for all platforms to take advantage of that feature. In this post I’ll talk about how to use custom APIs from each of our supported platforms, to have some reference material available while the official documentation doesn’t get updated.

.NET (Portable Library)

A small parenthesis before APIs - the portable library for Windows Azure Mobile Services is now a stable NuGet package. If you were waiting to use it because you don’t trust pre-release packages, there’s no need to fear anymore :)

Ok, custom APIs. There is a new method (with many overloads) in the MobileServiceClient class – InvokeApiAsync. There are a lot of overloads, but they can be grouped in basically three categories: typed JSON calls (with serialization of parameters and responses), untyped JSON calls (where parameters and return types are in the Newtonsoft.Json.Linq namespace), and “raw” HTTP request, which can be used for calls with any type of content type (not only JSON, but also XML, text, basically anything). Let’s look at all of them:

Typed API calls

There are four overloads in this category:

Simple POST requests, with or without a request body
- Task<T> InvokeApiAsync<T>(string apiName);
- Task<U> InvokeApiAsync<T, U>(string apiName, T body);
Requests with any HTTP method, with or without request body, and with optional query string parameters
- Task<T> InvokeApiAsync<T>(string apiName, HttpMethod method, IDictionary<string, string> parameters);
- Task<U> InvokeApiAsync<T, U>(string apiName, T body, HttpMethod method, IDictionary<string, string> parameters);

The first pair is the simplest of them – send an optional request body to the service, via a POST call. Let’s get a simple example API – called “orderpizza”, which exports a handler for the POST verb:

exports.post = function (req, res) {
var size = req.body.Size;
var flavor = req.body.Flavor;
var user = req.body.UserPhone;
var mySystem = require('./myPizzaSystem');
mySystem.orderPizza(user, flavor, size, function (error, orderNumber, deliveryTime) {
if (error) {
res.send(500, { error: 'There was a problem with your order' });
} else {
res.send(200, { OrderNumber: orderNumber, EstimatedDelivery: deliveryTime });
}
});
}

Now we can call it directly from our client:

public sealed partial class MainPage : Page
{
private async void btnStart_Click(object sender, RoutedEventArgs e)
{
try
{
var client = new MobileServiceClient("https://myservice.azure-mobile.net/", "mykey");
var myOrder = new PizzaOrder
{
Size = "Large",
Flavor = "Four Cheeses",
UserPhone = "555-555-1234"
};
var orderResult = await client.InvokeApiAsync<PizzaOrder, PizzaOrderResponse>("orderPizza", myOrder);
InformUser("My pizza will be delivered at {0}", orderResult.EstimatedDelivery);
}
catch (Exception ex)
{
InformUser("Error: {0}", ex);
}
}
}
public class PizzaOrder
{
public string Size { get; set; }
public string Flavor { get; set; }
public string UserPhone { get; set; }
}
public class PizzaOrderResponse
{
public int OrderNumber { get; set; }
public DateTime EstimatedDelivery { get; set; }
}

The second pair allows us to customize the request a little more. We can both change the HTTP verb, and we can also pass some additional parameters which are passed in the request query string, as shown in the example below (talking to the calculator API shown in the previous post).

public sealed partial class MainPage : Page
{
private async void btnStart_Click(object sender, RoutedEventArgs e)
{
try
{
var client = new MobileServiceClient("https://myservice.azure-mobile.net/", "mykey");
var arguments = new Dictionary<string, string>
{
{ "x", "7" }, {"y", "9" }
};
var calcResult = await client.InvokeApiAsync<CalculatorResult>("calculator/add", HttpMethod.Get, arguments);
InformUser("Result: {0}", calcResult.result);
}
catch (Exception ex)
{
InformUser("Error: {0}", ex);
}
}
}
public class CalculatorResult
{
public double result { get; set; }
}

One thing which should be noted: the ‘apiName’ parameter doesn’t need to be exactly the same name as the API on the server – in the case below, the route parameter is passed as the name. You can think of that first parameter as the path in the URL of the request.

Raw JSON API calls

The next set of overloads is the equivalent to the first, with the exception that instead of the generic typed parameters (and return values), we have

Simple POST requests, with or without a request body
- Task<JToken> InvokeApiAsync(string apiName);
- Task<JToken> InvokeApiAsync(string apiName, JToken body);
Requests with any HTTP method, with or without request body, and with optional query string parameters
- Task<JToken> InvokeApiAsync(string apiName, HttpMethod method, IDictionary<string, string> parameters);
- Task<JToken> InvokeApiAsync(string apiName, JToken body, HttpMethod method, IDictionary<string, string> parameters);

In the case of the pizza order system, if you didn’t want to create the types to be serialized, it could be implemented simply as follows:

public sealed partial class MainPage : Page
{
private async void btnStart_Click(object sender, RoutedEventArgs e)
{
try
{
var client = new MobileServiceClient("https://myservice.azure-mobile.net/", "mykey");
var myOrder = new JObject();
myOrder.Add("Size", "Large");
myOrder.Add("Flavor", "Four Cheeses");
myOrder.Add("UserPhone", "555-555-1234");
var orderResult = await client.InvokeApiAsync("orderPizza", myOrder);
InformUser("My pizza will be delivered at {0}", orderResult["EstimatedDelivery"].Value<DateTime>());
}
catch (Exception ex)
{
InformUser("Error: {0}", ex);
}
}
}

Or the call to the calculator:

private async void btnStart_Click(object sender, RoutedEventArgs e)
{
try
{
var client = new MobileServiceClient("https://myservice.azure-mobile.net/", "mykey");
var arguments = new Dictionary<string, string>
{
{ "x", "7" }, {"y", "9" }
};
var calcResult = await client.InvokeApiAsync("calculator/add", HttpMethod.Get, arguments);
InformUser("Result: {0}", calcResult["result"].Value<double>());
}
catch (Exception ex)
{
InformUser("Error: {0}", ex);
}
}

So, for simple, JSON-based requests or responses, those overloads should be enough for the large majority of the scenarios. But for scenarios where you need more fine-grained control on the request or response, or if you want to use non-JSON, then you need the “master” overload, which works for all scenarios.

Raw HTTP API calls

And the last overload uses the primitives from the System.Net.Http namespace to give full control

Task<HttpResponseMessage> InvokeApiAsync(string apiName, HttpContent content, HttpMethod method, IDictionary<string, string> requestHeaders, IDictionary<string, string> parameters);

For an example: if we have a service with an API which processes an image and returns a modified version of that image, we could call it like the example below.

var client = new MobileServiceClient("https://myservice.azure-mobile.net/", "mykey");
var imageBytes = await ChooseImage();
var content = new ByteArrayContent(imageBytes);
content.Headers.ContentType = new MediaTypeHeaderValue("image/png");
var response = await client.InvokeApiAsync("processImage", content, HttpMethod.Post, null, null);
var resultBytes = await response.Content.ReadAsByteArrayAsync();
await SaveProcessedImage(resultBytes);
InformUser("Image update complete");

And that’s it for the managed code version of the custom API.

JavaScript (Windows Store and HTML/JS apps)

As an untyped language, the JavaScript implementation is simpler than the one for the managed client. In fact, there is but one method which we need to invoke custom APIs in JS clients:

invokeApi(apiName, options)

Where ‘apiName’ has the same meaning as in the managed methods, and options is an object which can contain the following properties:

method (string): the HTTP method used in the request. Defaults to ‘POST’ if not set
body (variable): the body of the request. For JSON-based requests, passing arrays or objects will have them serialized. For non-JSON requests, the body should be a string value and it will be sent “as-is” (or to be more precise, encoded as UTF-8). Defaults to an empty body.
headers (object): any HTTP headers which you want to send with the request. For non-JSON requests, the object should have a ‘Content-Type’ header with the appropriate value. For requests with a body, the content-type will be set to JSON if it’s not explicitly set.
parameters (object): any query string parameters which will be appended to the request

The method returns a promise which will be fulfilled when the request is complete. In the case of success, the parameter passed to the callback contains an object which extends the XMLHttpRequest object with an additional member, called ‘result’ which is the parsed response body, in case of a JSON response. In the case of error, the parameter passed to the callback contains a member called ‘request’, which contains the XMLHttpRequest object used in the request, where you can query for properties such as status or responseText (among others of that object). Below is an example of a JS client calling the pizza API mentioned in the previous section:

var client = new WindowsAzure.MobileServiceClient('https://myservice.azure-mobile.net/', 'mykey');
client.invokeApi('orderPizza', {
method: 'POST',
body: { Size: 'Large', Flavor: 'Four Cheeses', UserPhone: '555-555-1234' }
}).done(function (response) {
informUser('My pizza will be delivered at ' + response.result.EstimatedDelivery.toString());
}, function (error) {
var xhr = error.request;
informUser('Error - status code: ' + xhr.status + '; body: ' + xhr.responseText);
});

Or in the case of a request to an API which routes XML requests to another server (well, why not? :), where we need to set some HTTP headers to values which we need, as shown below.

var client = new WindowsAzure.MobileServiceClient('https://myservice.azure-mobile.net/', 'mykey');
var body = '<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">' +
'<s:Body><Add xmlns="https://tempuri.org"><x>7</x><y>9</y></Add></s:Body>' +
'</s:Envelope>';
client.invokeApi('callService', {
method: 'POST',
body: body,
headers: { SOAPAction: 'https://tempuri.org/ITest/Add', 'Content-Type': 'text/xml' }
}).done(function (response) {
informUser('Result ' + response.responseText);
}, function (error) {
var xhr = error.request;
informUser('Error - status code: ' + xhr.status + '; body: ' + xhr.responseText);
});

And that’s it for JavaScript.

iOS

iOS is similar to JavaScript in that it doesn’t support JSON serialization of arbitrary types. As such, it has quite a simple API for invoking custom APIs as well, consisting of two methods:

invokeApi:(NSString *)apiName body:(id)body HTTPMethod:(NSString *)method parameters:(NSDictionary *)parameters headers:(NSDictionary *)headers completion:^(id result, NSHTTPURLResponse *response, NSError *error)
- Passes the body parameter through the NSJSONSerialization to be serialized to the request body, and passes the response through the same class to be deserialized and returned to the caller on the completion block.
invokeApi:(NSString *)apiName data:(NSData *)data HTTPMethod:(NSString *)method parameters:(NSDictionary *)parameters headers:(NSDictionary *)headers completion:^(NSData *result, NSHTTPURLResponse *response, NSError *error)
- Sends the data parameter as the request body directly, without applying any formatting, and sends the raw bytes of the result to the completion block.

And to continue on the pizza service, here’s how one would write code to order the pizza in an iOS application:

NSDictionary *order = @{@"Size": @"Large", @"Flavor": @"Four Cheeses", @"UserPhone": @"555-555-1234"};
[client invokeAPI:@"orderPizza" body:order HTTPMethod:@"POST" parameters:nil headers:nil completion:^(id result, NSHTTPURLResponse *response, NSError *error) {
if (error) {
[self informUser:@"Error: %@", error];
} else {
[self informUser:@"My pizza will be delivered at %@", [result objectForKey:@"EstimatedDelivery"]];
}
}];

And if you want to send / receive arbitrary data (non-JSON), you can use the other selector:

NSString *input = @"This is a string which will be passed to an API";
NSData *dataInput = [input dataUsingEncoding:NSUTF8StringEncoding];
NSDictionary *headers = @{@"Content-Type": @"text/plain"};
[client invokeAPI:@"reverseString" data:dataInput HTTPMethod:@"PUT" parameters:nil headers:headers completion:^(NSData *result, NSHTTPURLResponse *response, NSError *error) {
if (error) {
[self informUser:@"Error: %@", error];
} else {
NSString *reversedString = [[NSString alloc] initWithData:result encoding:NSUTF8StringEncoding];
[self informUser:@"Result: %@", reversedString];
}
}];

And in cases where there is no body in the request, you can simply pass ‘nil’ to it (in either of the methods), as in the example below.

[client invokeAPI:@"quoteOfTheDay" data:nil HTTPMethod:@"GET" parameters:nil headers:nil completion:^(NSData *result, NSHTTPURLResponse *response, NSError *error) {
if (error) {
[self informUser:@"Error: %@", error];
} else {
NSString *quoteOfTheDay = [[NSString alloc] initWithData:result encoding:NSUTF8StringEncoding];
[self informUser:@"Result: %@", quoteOfTheDay];
}
}];

A final note for the iOS client: the ‘response’ parameter passed to the completion blocks is where you’d get information such as the HTTP response headers, if necessary.

Android

With its typed serialization support, the android SDK is a lot similar to the implementation for the managed library, and it has the same nine overloads of the invokeApi method:

Typed API calls

As in the managed library, four overloads:

<E> void invokeApi(String apiName, Class<E> clazz, ApiOperationCallback<E> callback)
<E> void invokeApi(String apiName, Object body, Class<E> clazz, ApiOperationCallback<E> callback)
<E> void invokeApi(String apiName, String httpMethod, List<Pair<String, String>> parameters, Class<E> clazz, ApiOperationCallback<E> callback)
<E> void invokeApi(String apiName, Object body, String httpMethod, List<Pair<String, String>> parameters, Class<E> clazz, ApiOperationCallback<E> callback)

The first two send a ‘POST’ request with no query string parameters, while in the last two the caller can specify the HTTP method and also pass a list of query string parameters to be sent to the service. Continuing on our pizza order service, if we have two classes defined as follows:

public class PizzaOrderResponse {
public int OrderNumber;
public Date EstimatedDelivery;
}
public class PizzaOrder {
public String Size;
public String Flavor;
public String UserPhone;
}

We can call the API to order a new pizza with the code below:

PizzaOrder order = new PizzaOrder();
order.Size = "Large";
order.Flavor = "Four cheeses";
order.UserPhone = "555-555-1234";
mClient.invokeApi("orderPizza", order, PizzaOrderResponse.class, new ApiOperationCallback<PizzaOrderResponse>() {
@Override
public void onCompleted(PizzaOrderResponse result,
Exception error, ServiceFilterResponse response) {
if (error == null) {
informUser("Pizza will be delivered at " + result.EstimatedDelivery.toString());
} else {
informUser("Error: " + error.toString());
}
}
});

Similarly, if we want to use a typed version of the invokeApi methods to make some calculations, we can define the class:

public class CalculatorResult {
@SerializedName("result")
public double Result;
}

And invoke it with the client:

ArrayList<Pair<String, String>> parameters = new ArrayList<Pair<String, String>>();
parameters.add(new Pair<String, String>("x", "7"));
parameters.add(new Pair<String, String>("y", "13"));
mClient.invokeApi("calculator/add", "GET", null, parameters, CalculatorResult.class, new ApiOperationCallback<CalculatorResult>() {
@Override
public void onCompleted(CalculatorResult result,
Exception error, ServiceFilterResponse response) {
if (error == null) {
informUser("Result " + result.Result);
} else {
informUser("Error: " + error.toString());
}
}
});

As the previous example showed, annotations from the GSON library (like @SerializedName) will be honored when serializing / deserializing the calls.

Raw JSON API calls

For scenarios in which you either don’t want or cannot to create a type to pass arguments or receive results (minimizing number of types in project, schema now known at design time, etc.), you can use the JSON API calls, which use the JsonElement abstract class as the parameter to the ‘invokeApi’ and to the callback, in each of these four overloads:

void invokeApi(String apiName, ApiJsonOperationCallback callback)
void invokeApi(String apiName, JsonElement body, ApiJsonOperationCallback callback)
void invokeApi(String apiName, JsonElement body, String httpMethod, List<Pair<String, String>> parameters, ApiJsonOperationCallback callback)
void invokeApi(String apiName, String httpMethod, List<Pair<String, String>> parameters, ApiJsonOperationCallback callback)

As with the typed calls, the first two default to a ‘POST’ request, with no additional query string parameters, while in the last two the caller can specify the HTTP verb and a list of parameters to be sent in the query string of the request. In the callback, the result is passed as an instance of (a subclass of) JsonElement, as we can see in the pizza ordering example (last time, I swear) below

JsonObject request = new JsonObject();
request.addProperty("Size", "Large");
request.addProperty("Flavor", "Four cheeses");
request.addProperty("UserPhone", "555-555-1234");
mClient.invokeApi("orderPizza", request, new ApiJsonOperationCallback() {
@Override
public void onCompleted(JsonElement result, Exception error,
ServiceFilterResponse response) {
informUser("Pizza will be delivered at " +
result
.getAsJsonObject()
.get("ExpectedDelivery")
.getAsString());
}
});

I omitted the error handling in the example above for brevity, but it’s similar to the previous example.

Raw HTTP API calls

Finally, there are cases where we’re not dealing with JSON data; in this case, we can use the last overload of ‘invokeApi’, which gives the caller full control over the HTTP content (as a byte array) and headers.

void invokeApi(String apiName, byte[] content, String httpMethod, List<Pair<String, String>> requestHeaders, List<Pair<String, String>> parameters, ServiceFilterResponseCallback callback)

For completeness sake, an example of this overload:

byte[] bytes = getImage();
ArrayList<Pair<String, String>> headers = new ArrayList<Pair<String, String>>();
headers.add(new Pair<String, String>("Content-Type", "image/png"));
mClient.invokeApi("processImage", bytes, "POST", headers, null, new ServiceFilterResponseCallback() {
@Override
public void onResponse(ServiceFilterResponse response,
Exception error) {
saveImage(response.getRawContent());
}
});

And with this last Android overload we’re done with the client SDK support for custom APIs.

Wrapping up

I hope this clears some of the questions I’ve seen in the last few days on the forums. If you still have questions, please leave a comment or create a new thread in our MSDN Forum page.

Custom API in Azure Mobile Services – Client SDKs

.NET (Portable Library)

Typed API calls

Raw JSON API calls

Raw HTTP API calls

JavaScript (Windows Store and HTML/JS apps)

iOS

Android

Raw JSON API calls

Raw HTTP API calls

Wrapping up

Additional resources