Using the Streamr API GEN tool
[Note 01/21/21: The username/password auth shown in parts 1 and 2 has now been discontinued, so use Web 3 auth example explained in part 3.]
- You will need to have .NET Core 3.x installed on your machine. A small technical note: I actually am using the .NET Core 5 SDK preview release on my machine to do the builds, but the steps are identical for .NET Core v3.
- I will be using Visual Studio Community Edition (and possibly Visual Studio Code) although you can use your preferred editor.
- You will need to have a Streamr account already setup and you should have familiarized yourself with Streamr streams and data unions concepts, terminology and usage.
- You will need to have already setup at least one test stream and data union in Streamr Core (by using their website). The Streamr REST API is very full-featured and this tutorial only covers connecting, reading and writing.
- You should have already familiarized yourself with the Streamr REST API. I’m also assuming you are familiar with REST API and .NET development basics. I’m going to be using a Mac as dev box in this tutorial, but the steps would be nearly identical for Windows machines.
The code samples from this tutorial are on GitHub here.
Step 1: Setting up a test stream
In Streamr Core, you can see that I have already my account setup and that it has a test data stream (Robs Stream 1) created in it ready to use as shown below. You don’t need to worry about the data fields for the stream, streams can contain almost any arbitrary JSON data.
Step 2: Using the Streamr API Code Gen tool
The Streamr dev team have done some cool work for us by preparing an API explorer (map) tool for us. One of the things that tool offers is a way to auto generate a REST API client library to the Streamr YAML in various languages. While we could write .NET code straight to their REST API spec directly, calling REST APIs from .NET (or really any language) typically requires writing a hunch of “scaffolding” code to make things more manageable. That’s exactly what the code generator tool is doing for us, so it makes sense for us to leverage that code whenever possible. I’m not always a fan of auto-generated code but I’ve looked at what was generated in this case and it was pretty well done.
The structure of our app will therefore be layered as follows:
So, next, we’ll go over to the Streamr REST API map, and you will notice in the upper right corner a link at the top called “Code Generator.”
Clicking on the Code Generator link takes us to the next page, where we want to specific the type of code to generate. We will be selecting the following options:
- Target: Client
- Language/Framework: csharp
- Options: I just left all default values except one (select .net core project file). The target framework of v4.5 is fine for now also. Make sure .net core project file is checked also.
- Then click Submit. It should briefly “generating code” and present you with a download link. Go ahead and download the resulting .zip file and save it where you do your project builds and unzip it.
Step 3: Building the Client Library
Expanding the zip we should see the following files:
Let’s open the README.md file (I use the Chrome .md file viewer extension to view these files locally in the browser with proper formatting):
Some of the readme instructions are no current, so don’t follow them. Also, before we build anything, we notice that the project has a number of dependencies on other libraries:
RestSharp is a wrapper layer around System.Net HttpWebRequest, with some scaffolding code. The other are helper libraries for parsing/unparsing (serializing/deserializing) JSON in .NET. These libraries used are well known widely used, but any production usage would require close examination to make sure they work and are appropriate for your own environment and requirements. I have decided to leave them exactly as is. We can always go back and review this later if needed, and adjust package versions, etc. but our goal here is to get to using it in Streamr, so let’s keep going.
Next, open the IO.Swagger.sln in Visual Studio (note: make sure to install any updates Visual Studio wants to do first…which seems to be almost every day 😙).
With the solution open, we notice that there are updates for each of the NuGet dependency libraries: but do not update them at this time. We’re going to use the code (for now) exactly as it was auto-generated. So do Build -> Build All. You should get a successful build:
You will also notice the build generated quite a few warnings. For any production build, we’d want to go carefully resolve each of those (as well as update the referenced library NuGet packages to their latest), but for this tutorial, we’re just going to accept the library as is with the warnings.
Also note that this auto-generated library is targeting the .NET Framework 4.5 platform (not .Net Core). Again, for any production usage, we’d want to convert the entire library to .Net Core 3.1+, but for this demo, we’re just going to call the .NET Framework dll from a .Net Core 3 app. You wouldn’t necessarily want to mix frameworks in production (it can be done of course, but may not be ideal depending on your application requirements).
Next, in Part 2 of this tutorial, we’ll use this library from a .NET Core 3 console app to connect to Streamr and read and write to a test stream.
- Streamr Core
- Streamr Docs
- Steamr REST API Explorer, also info here
- .NET Core 3
- Microsoft Visual Studio Community Edition
- Microsoft Visual Studio Code
- Tutorial Sample Code GitHub
- RestSharp, RestSharp GitHub
- C#8 Async Streams
- Swagger API Code Generator GitHub