Tutorial: Create a Web API with ASP.NET Core in 1 minute
I have a confession to make as a C# developer. Even though I love C#, it’s strong typing, its compiler, its generics, LINQ, etc. sometimes make me jealous of PHP and Python developers. Both Python and PHP are far more dynamic in nature, and allow users to do things (because of their dynamic nature) that are almost impossible to do in C#. When a friend of mine showed me Django about a year ago, I felt almost shameful admitting that nothing similar exists for .NET. So, I decided to do something about it, and I created Magic.
CRUD, HTTP, and SQL
If you think about our problems as software developers, many of them can be reduced down to transferring JSON from the client to our backend. This problem is so common that it has been given its own acronym; CRUD; Create, Read, Update and Delete . HTTP has post, put, delete, and get. SQL has insert, update, delete, and select. They’re all arguably built around the same idea, the idea of CRUD.
So, obviously, there should exist some common denominator that allows us to automate the way we build our systems, assuming we have a database. Why do we even need to create this code ourselves? Why can’t the computer automatically create this code for us…?
Magic
Magic reads meta information from your database schema, and uses this meta information to scaffold HTTP REST endpoints, wrapping each CRUD operation in your database. The result becomes a thin layer of “Hyperlambda” code that sits between your controller endpoint and your database, allowing you to literally create and expose all CRUD operations on your database as HTTP REST endpoints by clicking a button.
Hyperlambda is a dynamic programming language and a DSL, which doesn’t require compilation, but is still blistering fast for these types of operations, as each Hyperlambda keyword is simply a wrapper around a C# class.
This allows us to easily create Hyperlambda “keywords” that authenticate and authorize the client, insert records into our database, read records, etc, all with only a few lines of code. Its syntax is so easily understood that even a computer can easily understand it and scaffold code in all possible permutations for it. The following video demonstrates the process.
In the video, Magic first reads the database schema for every table you have in your database. Then, it creates four Hyperlambda files, one file for each CRUD operation. These Hyperlambda files are given a path that is based upon their database object names, such that a database table named “foo” with a table named “bar” will have the “/files/magic/foo/bar.get.hl” as its path for the HTTP GET verb, pointing to a physical path on disc that contains a Hyperlambda file.
Then, I have a dynamic router controller that accepts “any” URL beneath “/magic”. This router will resolve towards my Hyperlambda files and execute them according to the URL it is given, combined with the HTTP verb that is used.
So, now, I have the ability to automatically create Hyperlambda code during runtime that wraps my existing databases without interrupting normal usage of my application. In addition, I have a routing mechanism that allows me to dynamically route HTTP requests towards files and folders in my server — the same files that are created during the scaffolding process.
For smaller and simpler types of apps, this literally becomes the entire backend Web API, and you can immediately start creating your frontend in, for instance, Angular or React. For more complex apps, requiring additional features that the above doesn’t give you, it becomes a great kick starter for your own backends, allowing you to easily mix in any amount of C# code and .Net controllers you wish.
It’s basically in such a regard a kind of “Django for .Net Core and C#”. And even if you have no needs for anything CRUD related at all in your own app, it’s still a great database administration system to administrate your databases in production and development environments, assuming you’re using MySQL or Microsoft SQL Server. In such a regard, it becomes the equivalent of “PHPMyAdmin for .Net Core”.
Features
Magic almost automatically takes care of authentication and authorization. For instance, each HTTP endpoint can be assigned a comma-separated list of “roles” that the client must be authenticated towards in order to be allowed to execute the endpoint’s code. The implementation uses a JWT token that is generated and returned to the client as the “authenticate” HTTP endpoint is invoked.
Some manual work in these regards still needs to be applied because Magic itself is “database agnostic.” But that’s literally a copy/paste job, which you can do in production if you wish. I have a video demonstrating it at the project’s website. By the way, passwords are stored using BlowFish hashing (“slow hashing”) and individual salting for those interested in the mechanics of this.
Magic also allows you to inform the scaffolding process that you want to log HTTP requests on individual endpoints. By default Magic is using log4net, but this can easily be exchanged by creating your own logging interface, and give to Magic through dependency injection. Everything in Magic is actually based upon IoC and Dependency Injection, of course … ;)
In addition, it allows you to declare what CRUD operations you want it to scaffold for you. Some database tables could be considered “read only” for instance, at which point you don’t want to have delete or update endpoints at all. That’s a simple checkbox during the scaffolding process in its frontend GUI.
Magic is blistering fast. First of all, each Hyperlambda file is tiny in size — only some 10-20 lines of code. This implies that parsing and evaluating its Hyperlambda files has a cost of almost nothing, at least compared to the relatively costly process of executing and processing SQL commands towards some database.
So, the additional cost of having this “tiny Hyperlambda layer” is almost nothing. Besides, the process of evaluating Hyperlambda has been optimized to the extreme. Hyperlambda is also 100% “async” in nature, meaning it will use the async features of C# and the CLR, as it evaluates your Hyperlambda files. This gives it an enormous amount of “throughput” and results in scalability features that easily matches any “pure” C# or .NET application. Not too bad without even having written a single line of code if you ask me!
Extending Hyperlambda with your own keywords is as easy as creating a simple C# class. Below is a real-world example from one of my own keywords, more specifically the [strings.starts-with] keyword, that returns true if some string starts with some other string.
namespace magic.lambda.strings
{
[Slot(Name = "strings.starts-with")]
public class StartsWith : ISlot
{
public void Signal(ISignaler signaler, Node input)
{
// Sanity checking.
if (input.Children.Count() != 1)
throw new ApplicationException("[strings.starts-with] must be given exactly one argument that contains value to look for");
signaler.Signal("eval", input);
input.Value = input.GetEx<string>()
.StartsWith(input.Children.First().GetEx<string>(), StringComparison.InvariantCulture);
}
}
}
Creating your own keyword is as easy as adding an attribute and an interface to your class, and you have a new “Hyperlambda keyword.” This feature gives the programming language some extreme “DSL capabilities.” Its resulting Hyperlambda can easily be read and understood by human beings.
However, you don’t need to understand Hyperlambda to use Magic, simply because your computer understands how to create and maintain your Hyperlambda. In such a regard, Hyperlambda becomes to Magic the equivalent of what CLR code is to C#.
You can see an example Hyperlambda HTTP endpoint below. Notice, there is no syntax highlighting at DZone for Hyperlambda, and not even in Visual Studio Code either for that matter, since Hyperlambda was invented by the author of this article - as far as I know, Hyperlambda has less than five users worldwide.
However, I do have a JavaScript-based Hyperlambda editor as an integral part of Magic, which syntax highlights your code, and even gives you autocomplete in case you want to study it :)
/*
* Declaration of arguments the endpoint can accept.
*/
.arguments
limit:long
offset:long
order:string
direction:string
id:long
name:string
/*
* Appending arguments in [slots.signal] below.
*/
add:x:./*/slots.signal/*/args
get-nodes:x:@.arguments/*
/*
* Invoking [slots.signal] with "magic.db.mysql.read".
*/
slots.signal:magic.db.mysql.read
database:magic_auth
table:roles
args
columns
id
name
/*
* Returning the results to caller.
* This will transform the result to JSON,
* and return to the client as the HTTP response.
*/
slots.return-nodes:x:@slots.signal/*
Note: Magic is a fairly new project, and it might contain bugs. It doesn’t have a million stars on GitHub, and as far as I know, no company on the Nasdaq index is currently using it. So, please be a little bit patient with it if you evaluate it. I have (of course) done all I can to make sure its code quality is as high as possible, and I remove every bug as I discover it; I will continue to maintain it in the foreseeable future, but there might be some “beta hickups” every now and then.
However, you can supply bugs and feature requests at my GitHub repository. If you have no bugs to submit, I would also appreciate any suggestions or kind words you may have about the project :).
Wrapping Up
All in all, Magic has the capacity to cut your job in half, allowing you to focus on the fun stuff, while your computer does boring work. Isn’t that why we invented computers? Hopefully, you have fun playing around with Magic, the same way I had fun creating it.
Thank you. If you like this tutorial please share it with others.
#ASP.NET #SQL #C# #Magic #API
