Maple Server

Meadow Foundation Maple Web Server

The Maple Web Server is primarily intended to provide RESTful endpoints from a device. It is modelled after ASP.NET Core and provides an easy to extend architecture with integrated JSON support via System.Text.Json.

Creating Web API Endpoints

A web API consists of one or more request handler classes that derive from RequestHandlerBase:

public class MyRequestHandler : RequestHandlerBase

Attribute Routing

Maple determines API call routing based on Attribute routing of handler methods.

Routing is supported to either absolute or relative paths.

Absolute Routing

If your route begins with a forward slash (/) then it is considered an absolute route, and requests will be routed to the provided route regardless of the Handler class name.

For example, the following will respond to GET requests to http://[meadow.address]/hello

public class MyRequestHandler : RequestHandlerBase
{
    [HttpGet("/hello")]
    public OkObjectResult Hello()
    { ... }
}

Relative Routing

If your route does not begin with a forward slash (/) then it is considered a relative route, and requests will be routed to the provided route prefixed with an abbreviated RequestHandler prefix. The route prefix is determined by using the class name and trimming off any "RequestHandler" suffix.

For example, the following will respond to GET requests to http://[meadow.address]/my/hello

public class MyRequestHandler : RequestHandlerBase
{
    [HttpGet("hello")]
    public OkObjectResult Hello()
    { ... }
}

But the following will respond to GET requests to http://[meadow.address]/webapi/hello

public class WebAPI : RequestHandlerBase
{
    [HttpGet("hello")]
    public OkObjectResult Hello()
    { ... }
}

Route Parameters

NOTE: Maple supports only a single parameter in a Route.

Maple supports providing a handler method parameter through the route path. Parameters are delineated by curly braces, and the parameter name in the route must exactly match the parameter name in the handler method signature.

As an example, a GET to the path http://[meadow.address]/orders/history/1234 would end up calling the following GetOrderHistory handler method with a parameter value of 1234:

public class OrdersRequestHandler : RequestHandlerBase
{
    [HttpGet("history/{orderID}")]
    public void GetOrderHistory(int orderID)
    {
        Debug.WriteLine($"{paramName}");
    }
}

Supported parameter types are:

• Numerics (byte, short, int, long, float, double)
• bool
• string
• DateTime
• Guid

Handler Caching

By default Maple will create a new instance of an API handler for every request received. If you want your application to reuse the same handler instance, which provides faster handler execution and decreases GC allocation, simply override the IsReusable base property and return true.

public override bool IsReusable => true;

Returning an IActionResult

It is recommended that all Handler methods return an IActionResult implementation. Extension methods are provided by Maple for common return objects including, but not limited to, ActionResult, JsonResult, OkResult and NotFoundResult.

For example, the following will automatically serialize and return a JSON string array with the proper content-type and return code.

[HttpGet("/JsonSample")]
public IActionResult GetJsonList()
{
    var names = new List<string> {
        "George",
        "John",
        "Thomas",
        "Benjamin"
    };

    return new JsonResult(names);
}

Sample Application

To see Maple Server in action, check out the unit sample applications or some practical samples up on Hackster.

	Control an RGB LED with Meadow and Xamarin using Maple! Get familiar with Maple, a RESTful web server running on Meadow and control an RGB LED remotely with a Xamarin.Forms app!
	Remote Control a Servo with Meadow and Xamarin using Maple! Get familiar with Maple, a RESTful web server running on Meadow and control a Servo remotely with a Xamarin.Forms app!
	Make your own OnAir sign with Meadow and Xamarin using Maple Turn your Meadow into a server with Maple, and use a Xamarin app to control it by sending client GET/POST with regular HttpClient in.NET.