Implementing a Custom Server-Side REST Endpoint

Applies To: Windows Azure Pack

The server-side provides a set of REST APIs that are called upon by the client-side to both retrieve data and perform operations. Both these types of operation will typically call upon a backend to get the actual data, or perform the actual operation. The controller, which is what implements the API, is usually an ASP.NET MVC controller returning JSON, and the backend will typically be Service Management API, but can be any other service accessible from an ASP.NET MVC web site.

Both the client-side and server-side can reside in the same Visual Studio project and are deployed to the same management portal(s).

Controller Class

The controller class is an instance of one of the ASP.NET MVC standard abstract classes Controller or AsyncController. It will typically be marked with the attributes [RequireHttps] to ensure only secure connections are allowed, [OutputCache] to disallow caching of responses, and [PortalExceptionHandler] which is described in the following Handling Errors section. To prevent Phishing attacks, methods in the controller are marked with [HttpPost]. This disallows HTTP GET requests while allowing HTTP POST requests. Neither the client nor server side frameworks put any restrictions on how the server and client sides talk to each other, with the exception of where interaction with the client-side framework’s Grid widget is required. In that case, see the following Returning Datasets section.

Returning Datasets

A dataset is a list of data to be shown by the UI, typically in a list (grid view). It is different from a standard reply in that the client-side framework handles retrieving it and displaying it in a grid. If a method is returning a dataset, typically represented in the UI as a list, it is recommended to use the method Controller.JsonDataSet as in the following example:

return this.JsonDataSet(listOfData);

This automatically wraps the listOfData dataset in a JSON wrapper suitable for processing by the client-side framework. For information about the client-side implementation, see How to Display a Grid in a Windows Azure Pack Management Portal Extension.

Performing Commands

Methods that perform commands in the controller will usually return a JSON object to show the operation worked. This can be as simple as a Boolean signifying success, or as complex as the data which has changed as a result of the operation. Nothing though is actually required by the client nor server-side frameworks.

Handling Errors

Exceptions that are thrown by the controller generally need to be shown to the user for further action or follow-up. The easiest way to do this on the server-side is to apply the [PortalExceptionHandler] attribute to your class. Any exceptions of type PortalException will be translated to correctly-modelled JSON, have the appropriate HTTP error code set, and be returned to the client-side for easy display with an error notification.An example of the JSON returned on error with the [PortalExceptionHandler] attribute is below:

{
  "message": "Fake Error",
  "ErrorMessage": "Fake Error",
  "httpStatusCode": "InternalServerError",
  "operationTrackingId": null,
  "stackTrace": null,
}

Any other type of exception will be shown as an empty HTTP 500 error, to avoid exposing internal details to the user.Further, stack traces will only be sent if the portal that the extension is running in has DevelopmentMode set to true. This can be changed in the management portal’s web.config file.For more information, see the section UI for Errors Returned from API Calls.

See Also

Windows Azure Pack Management Portal User Interface Extensions
How to Display a Grid in a Windows Azure Pack Management Portal Extension
Debugging a Windows Azure Pack Management Portal Extension