Butterfly.Web 
Simple RESTlike and Subscription API server in C#
Getting Started
Install from Nuget
| Name | Package | Install |
|---|---|---|
| Butterfly.Web |  |
nuget install Butterfly.Web |
| Butterfly.Web.EmbedIO |  |
nuget install Butterfly.Web.EmbedIO |
| Butterfly.Web.RedHttpServer |  |
nuget install Butterfly.Web.RedHttpServer |
Install from Source Code
git clone https://github.com/firesharkstudios/butterfly-web
Overview
Butterfly.Web defines an IWebApi interface to define RESTlike APIs and defines an ISubscriptionApi to stream real-time updates to clients.
Butterfly.Web.EmbedIO implements the Butterfly.Web interfaces using the lightweight EmbedIO web server.
Butterfly.Web.RedHttpServer implements the Butterfly.Web interfaces using the Kestral based RedHttpServer.
Using IWebApi
An IWebApi instance allows defining a RESTlike API like this...
// Create an IWebApi instance using EmbedIO or RedHttpServer
webApi.OnPost("/api/todo/insert", async (req, res) => {
var todo = await req.ParseAsJsonAsync<Dict>();
// Do something to insert the todo
});
webApi.OnPost("/api/todo/delete", async (req, res) => {
var id = await req.ParseAsJsonAsync<string>();
// Do something to delete the todo
});
// Don't forget to compile
webApi.Compile();Request Handling
There are many ways to receive data from a client...
// Using path params
webApi.OnGet("/api/todo/{id}", (req, res) => {
// Opening /api/todo/123 would print id=123 below
Console.WriteLine($"id={req.PathParams["id"]}");
});
// Using query params
webApi.OnGet("/api/todo", (req, res) => {
// Opening /api/todo?id=123 would print id=123 below
Console.WriteLine($"id={req.QueryParams["id"]}");
});
// Using post body that is JSON encoded
webApi.OnPost("/api/todo", async(req, res) => {
// A javascript client posting JSON data with...
// $.ajax('/api/todo', {
// method: 'POST',
// data: JSON.stringify({ id: "123" }),
// });
// would echod id=123 below
var data = await req.ParseAsJsonAsync<Dictionary<string, string>>();
Console.WriteLine($"id={data["id"]}");
});
// Using post body that is URL encoded
webApi.OnPost("/api/todo", async(req, res) => {
// A javascript client posting JSON data with...
// var formData = new FormData();
// formData.append("id", "123");
// $.ajax('/api/todo', {
// method: 'POST',
// data: formData,
// });
// would echod id=123 below
var data = await req.ParseAsUrlEncodedAsync();
Console.WriteLine($"id={data["id"]}");
});Response Handling
There are many ways to send a response to a client...
// Respond with plain text
webApi.OnPost("/api/todo", async(req, res) => {
await res.WriteAsTextAsync("OK");
});
// Respond with JSON
webApi.OnPost("/api/todo", async(req, res) => {
await res.WriteAsJsonAsync(new {
result = "OK"
});
});
// Redirect the client
webApi.OnGet("/api/todo/{id}", (req, res) => {
res.SendRedirect("/api/todo/not-found");
});Using ISubscriptionApi
An ISubscriptionApi instance allows clients to receive real-time updates like this...
// Create an ISubscriptionApi instance using EmbedIO or RedHttpServer
subscriptionApi.OnSubscribe("echoes", async(vars, channel) => {
int count = 0;
return Butterfly.Util.RunEvery(() => {
channel.Queue("Echo", $"Echo #{++count}");
}, 2000);
});A client subscribing to the echoes subscription above would receive messages every two seconds (first message would have type Echo and text Echo #1).
The subscription handler must return an IDisposable instance that is disposed when the client unsubscribes or disconnects.
Using EmbedIO
EmbedIO is a capable low footprint web server that can be used to implement both the IWebApi and ISubscriptionApi interfaces.
The EmbedIOContext class is a convenience class that creates IWebApi and ISubscriptionApi instances using an EmbedIO web server.
In the Package Manager Console...
Install-Package Butterfly.Web.EmbedIO
In your application...
var context = new Butterfly.Web.EmbedIO.EmbedIOContext("http://+:8000/");
// Declare your Web API and Subscription API like...
context.WebApi.OnPost("/api/todo/insert", async (req, res) => {
// Do something
});
context.WebApi.OnPost("/api/todo/delete", async (req, res) => {
// Do something
});
context.SubscriptionApi.OnSubscribe("todos", (vars, channel) => {
// Do something
});
context.Start();Using RedHttpServer
RedHttpServer is a Kestrel/ASP.NET Core based web server that can be used to implement both the IWebApi and ISubscriptionApi interfaces.
The RedHttpServerContext class is a convenience class that creates IWebApi and ISubscriptionApi instances using RedHttpServer.
In the Package Manager Console...
Install-Package Butterfly.RedHttpServer
In your application...
var context = new Butterfly.Web.RedHttpServer.RedHttpServerContext("http://+:8000/");
// Declare your Web API and Subscription API like...
context.WebApi.OnPost("/api/todo/insert", async (req, res) => {
// Do something
});
context.WebApi.OnPost("/api/todo/delete", async (req, res) => {
// Do something
});
context.SubscriptionApi.OnSubscribe("todos", (vars, channel) => {
// Do something
});
context.Start();Contributing
If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.
Licensing
The code is licensed under the Mozilla Public License 2.0.
