An "opinionated", minimalistic, and super simple HTTP REST library for .Net built on .Net Standard. The whole idea
with the library, is to provide a single line invocation for HTTP REST invocations from C# and other CLR languages.
Basically, the library simply wraps HttpClient, allowing you to invoke REST endpoints, passing in your own types,
that are automatically serialized to JSON, and return types from your endpoints, automatically de-serialized as JSON.
Below you can see an example of usage.
var result = await client.GetAsync<Post[]>("https://foo-bar.com/posts");The idea is that you provide your request type (if any), and your response type as generic arguments to its
IHttpClient interface methods, and the library will perform automatic conversion on your behalf, reducing your
HTTP REST invocations to a single line of code, resembling "function invocations". This provides an
extremely simply to use API, and also allows you to have large amount of cohesion in your own code. After all,
HTTP is a request/response type of model, arguably much more suited for "functional style" of programming,
than Object Oriented programming.
The library supports the 4 most commonly HTTP verbs, below is a list.
- POST
- GET
- PUT
- DELETE
The library provides 5 dead simple methods throughs its IHttpClient interface, which maps to the above HTTP verbs
somehow. These methods should be fairly easily understood by most C# developers.
- PostAsync(url, request)
- PutAsync(url, request)
- GetAsync(url)
- GetAsync(url, callback)
- DeleteAsync(url)
The POST and PUT verbs requires payload objects, that you provide as typed generic arguments, while the DELETE and GET
verbs does not allow you to supply payloads. In addition you can optionally supply a dictionary of HTTP headers, that
will correctly decorate your HTTP content and your HTTP request message, depending upon where it belongs. There are also
convenience methods for invoking HTTP REST endpoints with "Bearer" authorization tokens, automatically taking care of
adding your tokens correctly to your requests.
In addition the library will "intelligently" handle Stream requests for POST and PUT, allowing you to
supply a Stream as a request object, which will serialize your stream directly on to the HTTP request
stream, without loading its content into memory first. The GetAsync method also has an overload allowing
you to access the response stream directly, allowing you to download large files, without first loading them
into memory.
Apart from the above features, the library does not really give you much options, and is to be considered an "opinionated" HTTP REST library, and its purpose is not to support every possible configuration you can imagine, since its purpose is first and foremost to be dead simple to use, and force creation of better HTTP REST invocations. However, if you have that "one feature request you simply must have", feel free to supply a request in the issues. If it makes the API more complex, I might not want to support it though.
You can either download the latest release, or install it directly through NuGet using the following installation command.
Install-Package magic.http
The library is created to be "dependency injection friendly", which implies you can use its IHttpClient interface
for accessing its functionality, using something such as the following to wire up your interface to its implementation,
for then to retrieve instances to its implementation using dependency injection later in your own code.
/*
* Somewhere where you wire up your IoC provider.
*/
services.AddTransient<IHttpClient, HttpClient>();
services.AddHttpClient();
The last part is important to make sure you register the IHttpClientFactory required to create
instances of HttpClient to use internally in the library. Magic will use "magic" as a named
instance as it creates its HttpClient, allowing you to fiddle with configuring it as you see fit,
for advanced usage. Just remember that all HttpClients in magic will be created using this name.
And yes, the Magic HttpClient should be registered as a "transient" service.
However, the library is first and foremost created to support JSON and/or large files as payloads and response values, and the "philosophy" of the library is to allow you to create HTTP REST requests with a single line of code, to such facilitate for simplified code, and better cohesion in your own code. The library will not support every single permutation of HTTP requests possible to create, due to that this would complicate its code, and results in that it degrades over time. The library is created to eliminate an entire axiom of bugs related to wrong usage of HttpClient. You can read some of its rational below.
The source code for this repository can be found at github.com/polterguy/magic.http, and you can provide feedback, provide bug reports, etc at the same place.
This project is the copyright(c) 2020-2021 of Thomas Hansen thomas@servergardens.com, and is licensed under the terms of the LGPL version 3, as published by the Free Software Foundation. See the enclosed LICENSE file for details.