DEV Community: Irina Scurtu

Enabling gRPC server reflection

Irina Scurtu — Tue, 13 Dec 2022 14:39:11 +0000

Enabling gRPC server reflection will allow you to easily call your gRPC services from Postman without actually loading the protofile .

PostMan will help you test your gRPC services, by giving you the same look and feel as a you would have with a traditional HTTP API.

gRPC uses binary serialization, which means that is not human readable as JSON is. Is still possible to use grpcurl or similar tools, but you will not be able to decipher binary. Having the right tools will help you understand gRPC faster, because it has a slightly different vocabulary.

When you open PostMan and click the New button , you can choose to issue gRPC requests. Thankfully, this is not in beta anymore.

PostMan New menu options

To issue a gRPC request, you will need to specify the URL of the server (as you would do with a regular RESTful API), and then give PostMan access to the proto file that is implemented on the server. In this case, you need to help the tool a bit, so you can gain access to available functionality.

To do that you can simply import the proto file or let PostMan discover what is available.

In this case we will use the second option, because we would want our service operations to be somehow discoverable.

Different ways of ‘accessing’ the proto file contract

Now, if we try to click the highlighted option, we will get a big red error. This is as if our server throws an Unimplemented exception from a method.

In reality, if we look at the logs, it actually does throw that kind of exception.

info: Grpc.AspNetCore.Server.Internal.ServerCallHandlerFactory[1]
      Service 'grpc.reflection.v1alpha.ServerReflection' is unimplemented.

Enabling gRPC server reflection requires a few code tweaks because we actually need to an implementation that allows reflection over our grPC services.

First, install Grpc.AspNetCore.Server.Reflection NuGet package. This will contain the ServerReflection implementation that will we need, that allows external services and tools to discover existing methods

Next, we need to add the middleware and then map the incoming gRPC requests to the Reflection Service.

builder.Services.AddGrpcReflection();

IWebHostEnvironment env = app.Environment;
if (env.IsDevelopment())
{
   app.MapGrpcReflectionService();
}

Once you did this, PostMan will successfully discover the available gRPC methods, and you will be able to call invoke these from the UI

gRPC methods

That’s it! A package and a few lines of code and you will enable gRPC server reflection.

The post Enabling gRPC server reflection appeared first on Irina Scurtu.

Using custom media types in .NET

Irina Scurtu — Fri, 01 Apr 2022 09:31:32 +0000

How to use and create custom mime types in .NET? How to respond to different mime-types in your Web API? Use the same HTTP Verb but hit different actions based on the Content-Type header value? Have 2 methods that have the same number of parameters and respond to the same HTTP Verb?

These are questions that some of the developers seek answers to.

Accept & Content-Type

There are 2 very important headers that are often overlooked, Accept and Content-Type, and play a major role in a process called Content-Negotiation.

Accept header

With this header, the API consumer tells the server what is the mime type it expects as the format for the response.

eg. Accept: application/json or Accept: application/xml.

If the server can’t build a response with the requested format, it will return a 406 – Not Acceptable status code.

Content-Type

Describes the format of the body of the request that is sent to the server or to the client. This tells the server: “Hey, the body you will receive has this format, can you interpret it?”

If the server can’t read the content of the body, it will return a 415 Unsupported Media Type status code_._

_Content-Negotiation_ is the process that happens with every request, where basically the two parties involved (i.e the Server and the Consumer/Client) do exactly that. : negotiate on the content. Depending on the format send as value for these 2 header properties, the result can differ.

When we talk about APIs orREST-ful APIs we implicitly talk about different representations of resources.

Introducing the problem

Let’s say we have an API that deals with speakers. For these, we store all kinds of info, but not all are needed every time. Maybe you need to return a full object in one scenario, and just a few properties in another one, like below.

   public class SpeakerModel
    {    
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Bio { get; set; }
        public string JobTitle { get; set; }
        public string Website { get; set; }
        public string Email { get; set; }
        public string TwitterHandle { get; set; }
        public string CompanyName { get; set; }
        public string Address { get; set; }
        public string Phone { get; set; }
        public string PassportDetails { get; set; }
    }

public class TrimmedSpeakerModel
 {    
        public int Id { get; set; }      
        public string FirstName { get; set; }
        public string LastName { get; set; }
}

To achieve this, people end up creating new endpoints because the platform forces us to do so, in a way. We have the controller and in the controller we implement implement 2 actions, with different name, and different routes.

/api/speakers and /api/speakers/trimmed are basically two representations of the same resource. It shouldn’t matter what scenario you are in, the endpoint should still be something similar to /api/speakers to the outside world.

In the example below we focus on the output, and not the logic in the action.

        [HttpGet("{speakerId}")]
        public IActionResult GetSpeakerFull([FromQuery] int speakerId)
        {
           return Ok(new SpeakerModel());
        }

        [HttpGet("{speakerId}")]
        public IActionResult GetSpeakerTrimmed([FromQuery] int speakerId)
        {
            return Ok(new SpeakerTrimmedDto());
        }

Something like this would be possible without getting an error from the routing mechanism. We know we have a GET request, but which one of the two actions should be selected? We need to help the framework to distinguish between the two of them.

Introducing media types(MIME types)

A media type (also known as a Multipurpose Internet Mail Extensions or MIME type) indicates the nature and format of a document, file, or assortment of bytes. MIME types are defined and standardized in IETF's [RFC 6838](https://datatracker.ietf.org/doc/html/rfc6838).

Custom media types

A custom media type is a media type that we can create, often containg vnd as . This media type is significant to the specific business or domain.

You will often find vendor-specific media types used by different businesses as a mean to address specific customers trough the same api. There are hundreds of vendor-specific media types registered with IANA. Such example can be application/vnd.mspowerpoint.

GitHub uses them in their API, and a lot of other businesses.

Media type structure

Media type structure

Responding to media types in controllers

To respond to a specific media type in our action, all you have to do is annotate with the [Consumes("")] attribute, passing the value of your media type.

This attribute will allow us to have actions that return different representations of the same resource.

        [HttpGet("{speakerId}")]
      [Consumes("vnd.speaker.trimmed")]
        public IActionResult GetSpeakerTrimmed([FromQuery] int speakerId)
        {
            return Ok(new SpeakerTrimmedDto());
        }

You will have to send Content-Type : vnd.speaker.trimmed when you make the request, to hit the action.

In a similar manner you can use the [Produces("")] attribute to help the routing mechanism when you want a specific format returned. This attribute will look after Accept header value. Bear in mind that it will work out of the box only with the mime types supported by the framework. Otherwise you will need to create an OutputFormatter, and register it.

In summary

The approach with media types can be used for versioning too. You can read more about versioning your API here.

You can create your custom vendor-specific mime types, and include versions in them. From there you leave the routing mechanism to do its job.

Use this wisely, because currently It will cause a swagger loading error. I’m still looking for a way around it. If you know how, drop a comment or a DM

The post Using custom media types in .NET appeared first on Irina Scurtu.

The .NET Docs Show – Versioning REST APIs

Irina Scurtu — Tue, 11 May 2021 07:13:30 +0000

The post The .NET Docs Show – Versioning REST APIs appeared first on Irina Scurtu.

How to build REST-ful APIs

Irina Scurtu — Tue, 02 Mar 2021 12:25:57 +0000

Thank you Edwin van Wijk and Sander Molenkamp for inviting me.

You can see more interesting videos on DotNETFlix channel on different topics, or read about REST

The post How to build REST-ful APIs appeared first on Irina Scurtu.

Naming your REST endpoints

Irina Scurtu — Thu, 19 Nov 2020 20:04:46 +0000

How to name your REST endpoint? How does your endpoint look? Are there any guidelines or best practices? How to name your endpoints? Let’s

A short introduction

We often use APIs to implement CRUD operations, or most APIs start like this, but all of them evolve over time.

CRUD is an acronym that stands for Create, Read, Update, Delete. And these are all the operations that you can apply to a specific resource.

Let’s take childish example, and say you need to manage pets for a veterinary cabinet and you are interested in cats:

/api/getAllCats– wouldn’t /api/cats be easier to remember?

/api/newCat – how about /api/catsand use POST as HTTP Verb?

/api/getBlackCats– why should you have a different endpoint? /api/cats?color=blackwill have the same path, but the parameter value will change an get you a lot of flexibility

/api/getCatsOwners– how about /api/cats/{id}/owners– this way you will know exactly to which cat you are reffering. The one with the {id} in the URL path.

/api/getHungerLevel– hunger level of…? cat? which cat? maybe is youru hunger level?

If you look at the endpoints, are very hard to remember, and once you add more operations, it will be even harder to remember and harder to manage. Plus, you have no reason to include get{something} in the endpoint or have tons of endpoints. The HTTP verb will be the one that tells what operation you are doing. Either is a GET, a POST or something else. KISS, as in code, also applies here. And more than that, we need to keep in mind that we need to leverage the underlying protocol as much as we can.

In my opinion, an endpoint in a REST API should be self-explanatory. Just by looking at the URL, you( and the server) should be able to tell what is the resource it handles without needing a manunal.

One ot the things REST is trying to do, is to remove the uglyness we all dealt with in SOAP. SOAP exposed a set of operations in a WSDL file, and to ‘call’ those operations we made a single type of call(POST or GET). REST is trying to get rid of that paradigm and get us closer to the underlying protocol.

Luckily, if you are nostalgic(or not) we have tools like Swaggerand the Open API standard to help us with the documentation, but even so, and URL should express intent in the ‘eyes’ of the consumer.

COOL URI’s don’t change.

Let’s look at the 2 endpoints that you will need in a REST API.

An endpoint for the collection

/api/cats

This will allow you 2 operations:

retrieve the collection by HTTP GET (a read)
Create a new resource by using HTTP POST (a create)

An endpoint for a specific item

/api/pets/{id}

This will allow you 4 operations:

retrieve the item by using HTTP GET(a read)
update an existing resource by using HTTP PUT(an update) or HTTP PATCH
delete and existing resource by using HTTP DELETE(a delete)

Related/hierarchical resources

Any hierarchical resource can be represented further in the URL path, but the convention remains, and applies down in the hierarchy.

Let’s take the example of wanting to represent the owners of a specific cat:

/api/cats/{id}/owners

Looking at this URL we realize that in the cats collection, we are interested in the specific {id} of the cats, and from this specific cat, we want the owners collection.

When we obtain the list of owners, we might be interest to obtain a specific one, and we can take another step : /api/cats/{id}/owners/{ownerid}

You are not forced to model your data and store it in the database according to the endpoints, or the other way a round. Remember, in REST, you work with representations of resources, and those representations are handled by you. At the server level, for more decoupling and simplicity, you should use DTOs to transform or aggregate data.

Takeaways

Name your endpoints in such a way to have meaning for the business and your consumers
You don’t need a different endpoint to represent a new operation. You can give meaning to your request by using the right HTTP verb
You can use GET, POST to the same endpoint /api/cats : the end result will be different.
you need two endpoints to represent major operations on a resource
Variations of specific resources can be represented as parameters in the query string, not different endpoints.

In conclusion, it is up to you how you shape your endpoints. There is no constraint in this. As long as it makes sense for the business, expresses the intent, and is specific enough.

The meaning for each request/response should be added by using the right HTTP Verbs, headers and status codes.

The post Naming your REST endpoints appeared first on Irina Scurtu.

.NET Core with NGINX on Linux

Irina Scurtu — Wed, 07 Oct 2020 09:49:23 +0000

Having .NET Core with NGINX on Linux is easier that you might imagine. In this article I will talk about my experience related to NGINX and what it takes to configure it for the first time. If you come from an IIS/Windows world like me, where you know everything by heart, the declarative approach in NGINX might be a bit odd.

I already have Kestrel, why do I need something else?

Kestrel is the default server implementation for ASP.NET Core, and it is super fast, cross-platform, customizable and it can run on its own. It looks like it is the perfect server, but it was lacking a lot of features related to security. Another thing about Kestrel is that “used as an edge server without a reverse proxy server doesn’t support sharing the same IP and port among multiple processes”.

Although is not required, it is recommend to have a reverse proxy in front of Kestrel because it will give you an extra layer of configuration and defense and integrates smoothly with the existing infrastructure.

What is NGINX?

NGINX is an open source software for web serving, load balancing, media streaming, that also has reverse proxy capabilities. One of the goals behind NGINX was to create the fastest web server out there. Now, is one of the most popular servers out there.

Installing NGINX on Linux

Depending on your Linux distribution the package manager might differ. I had Red Hat sudo yum install nginx did the trick. After a successful installation you will find the files and folders for NGINX under /etc/nginx path on the server looking pretty much like this( without the highlighted folders)

nginx structure

One of the most important files out there is the nginx.conf file that will contain or reference other configurations for your web apps. Bear in mind that, in order to be able to start NGINX server this configuration will have to be valid.

Configuring NGINX for all your apps

Now, I’ve cleaned up a bit the default nginx.conf and it looks like this:

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;
events {
    worker_connections 1024;
}

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
    '$status $body_bytes_sent "$http_referer" '
    '"$http_user_agent" "$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log main;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    # Load modular configuration files from the /etc/nginx/conf.d directory.
    # See http://nginx.org/en/docs/ngx_core_module.html#include
    # for more information.
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;

}

For easier formatting, I used Visual Studio Code with 2 extensions: Nginx configuration and Nginx Formatter.

At line 28, I’ve added an include statement because I want to place all my configurations for different website in separate files, in sites_enabled folder.

After that, I’ve created the sites_enabled folder, and the certs folder (that will contain certificates). In the sites_enabled folder, I’ve created a file named myapi.conf and inside it, I’ve added this:

server {
    server_name myserver;
    root /var/opt/myapps/ui;

    index index.html index.htm index.nginx-debian.html;

    location / {
        try_files $uri $uri/ /index.html;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    location /api {
        proxy_pass http://localhost:4906;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

In the configuration file I have 2 ‘location’ sections, one for an UI app, and one for the API. The two apps I want to be served from the same ‘domain’ but on a different path:

the ui app from the root like /myapp
the api from something deeper in the hierarchy like: /myapp/api

Once this is done, you can test the nginx configuration by running nginx -t -c /etc/nginx/nginx.confin the terminal. If that is successful, you can go ahead, start NGINX server

Useful NGINX commands

sudo nginx service start

sudo nginx service restart

sudo nginx service status

In summary

We looked at how to configure .NET Core with NGINX on Linux, but the same configs will work on Windows also. The only thing you need to do besides configure NGINX is torun the API as a Linux Service, and to make sure is up.

In a following post we will add https in front of our API, because we need to care about security.

The post .NET Core with NGINX on Linux appeared first on https://irina.codes, Irina Scurtu's blog

.NET API as a Linux Service

Irina Scurtu — Tue, 06 Oct 2020 11:13:39 +0000

.NET API as a Linux Service is just one of the many options when it comes to hosting.

One thing I love about .NET Core is that it runs everywhere. Running .NET APIs as Linux services, allows different organizations to reduce some costs by maybe reusing infrastructure. Before .NET Core, .NET was almost synonymous with Windows. The only server for .NET was IIS.

Now you have a ton of options when it comes to hosting your .NET applications.

You want to keep running it on Windows? You can host and install it as a Windows Service with NSSM. Do you want Kestrel instead of IIS Express? No worries, you can do that. Nowadays, sky is the limit when it comes to hosting a .NET API.

One thing you will need to do is to install .NET on the server. You can read herehow to install .NET on different Linux distributions. (If you never did this or you are not an experienced Linux user).

What you need

– Putty or a way to connect to your Linux server

– sudo rights or execution rights on the server

Running an API as a Linux Service

If you have your API in good standing, versioned,and with the right status codes and you chose Kestrel, the only thing you need to do is to create a .service file and to put it on your Linux server. In my case, the API was hosted on a RedHat distribution.

The service content will be a file with the .service extension (let’s call the file myapi.service), placed under /etc/systemd/system path.

The .service file will contain info related to what it will need to run and from where, and a few flags.

[Unit]
Description=Awesome API
[Service]
WorkingDirectory=/var/opt/myapps/myapi
ExecStart=/usr/bin/dotnet /var/opt/myapps/myapi/MyApi.dll
Restart=always
RestartSec=10
SyslogIdentifier=myapi
User=root
Environment=ASPNETCORE_ENVIRONMENT=Development
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
[Install]
WantedBy=multi-user.target

Assuming you have sudo rights, you will need to start the service by running systemctl start myapi.service

Useful linux commands

systemctl stop myapi.service stops your service

systemctl start myapi.service starts your service

systemctl status myapi.service returns the status of your service. Is useful when you want to make sure the service is running or for debugging purposes. The response will contain some aditional info, depending on what you have configure, but it will look pretty much like this:

Once you have your NET API as a Linux Service up and running, you might need to make it run on HTTPS.

You’ll see in another article how you can configure NGINX Reverse proxy to have Https.

The post .NET API as a Linux Service appeared first on Irina Scurtu.

Status Codes for REST APIs

Irina Scurtu — Thu, 16 Jul 2020 07:34:19 +0000

When it comes to Status Codes for REST APIs, we are all in a hurry to deliver functionality and we often ignore them. Come as it may. We use what we get. And that’s it.

REST as a concept should also be about meaning, longevity and empathy towards our API consumers. We should be able to look at a request/response in isolation and understand what is wrong or what happened.

Choosing Status Codes for REST APIs sometimes is not easy, but at least we should give this a thought.

In this article, I will talk about Status Codes for REST APIs: the most common and the ignored ones, and a few usage scenarios.

We all know that we have 5 categories when it comes to status codes. And depending on the response category we should be able to tell what happened with that request. Was the request bad? There is an error processing it?

Status Codes – Categories

1xx – Informational
2xx – Success
3xx – Redirect
4xx – Client Error
5xx – Server error

I’ve seen APIs where the status code was 200 OK, but the response body looked like this:

In this case, me or my app, as an API consumer…what should I understand? Was my request successfully processed, or…. am I unauthorized? #confusing. So don’t do this in your APIs.

2xx – Sucess status codes

These are success status codes because they start with 2, but in particular, that code should express exactly what happened. You shouldn’t return 200 OK for all the scenarios and then write an error in the body. (if you want to add meaning and have a well-rounded API.)

200 OK

When the response what processed with success, and usually has a response body.

201 Created – As a response for a POST request that has the effect of creating a new resource. This should be accompanied by a Location header indicating the location for the newly created resource

202 Accepted – For scenarios where there is no need for a response body. e.g for queuing something for later processing.

Also, this works very fine with the Location header, for polling scenarios, where you call the endpoint from time to time to see the status of a resource processing

204 No Content

4xx – Client errors

400 – Bad Request

Bad Request is in my opinion, one of the most miss-used status codes. I’ve seen it returned when due to some business logic the request couldn’t be processed, but the request was well formed.

Think about it – when the request is well-formed, it has the parameters, the body and everything all good, but is a business rule on the backend that prevents that request from being processed….is not a Bad Request. Is anything but a Bad Request.

When you see a Bad Request, the tendency is to look at the content of the request to see what is wrong, fix that, and issue the request again.

Dummy Scenario : Online Store. You can’t create 2 products with the same name and brand.

Status Code: 409 – Conflict not Bad Request. Here you are basically informing your consumer that there is a rule somewhere that prevents you to add that resource; hence, a 409 – Conflict

401 – Unauthorized , 403 – Forbidden

404 – Not Found – resource is not there, or maybe it was deleted.

406 – Not acceptable – when the server can’t return a response that matches the Accept header of the request. To force .NET to take the Accept header into consideration you will need to set a flag to true:

 services.AddControllers(setupAction =>
 {
    setupAction.ReturnHttpNotAcceptable = true;
  })

409 – Conflict – When there is a business rule that prevents you from creating that resource as a result of a POST. Another scenario can be with using PUT to update a specific resource, and due to its state, you can’t.

410 – Gone

415 – Unsupported Media-Type ; When the server can’t understand the body of the request, due to a wrong Content-Type header, or limited capabilities on the server.

For example, if you try to send an XML in the request but the server doesn’t know how to read XML, you should get this status code.

422 – Unprocessable Entity – the server understands the request, the request is well-formed but due to some rules, it can’t be processed. It can be used instead of 409 – Conflict and also covers a lot of ground. You can configure this inStartup.cs by leveraging ApiBehaviourOptionslike this:

           services.AddControllers()
                .ConfigureApiBehaviorOptions(setupAction =>
            {
                setupAction.InvalidModelStateResponseFactory = context =>
                {
                    var problemDetails = new ValidationProblemDetails(context.ModelState)
                    {
                        Type = "https://yourApi.com/modelvalidationproblem",
                        Title = "One or more model validation errors occurred.",
                        Status = StatusCodes.Status422UnprocessableEntity,
                        Detail = "See the errors property for details.",
                        Instance = context.HttpContext.Request.Path
                    };

                    problemDetails.Extensions.Add("traceId", context.HttpContext.TraceIdentifier);

                    return new UnprocessableEntityObjectResult(problemDetails)
                    {
                        ContentTypes = { "application/problem+json" }
                    };
                };
            });

This way, you can hook yourself to the ModelState and treat validation errors as 422 status codes instead of Bad requests if you need that. You can find more examples in the docs. As a result, ASP.NET higher than 2.1 generatesRFC-7807 compliant responses.

As a side note, if you configure ApiBehaviour to return BadRequest for model validation, you won’t need to scatter all over your controllers these lines of code:

if (ModelState.IsValid) 
 {
     return BadRequest(ModelState);
 }

Conclusion

Even though the most common status codes that might fit a lot of scenarios, we should bear in mind that there are around 63 of them!! Why? For us to use!

If we don’t use “one size fits all” in terms of the technology we choose, why do we apply this on status codes?

If don’t think about versioning, or headers, or HATEOAS in our APIs, at least we should have the right status codes.(and verbs, and naming )

The post Status Codes for REST APIs appeared first on Irina Scurtu.

Extending EF Core DbContext

Irina Scurtu — Fri, 29 May 2020 14:44:30 +0000

Entity Framework allows you to extend the DbContext class to add your own entities, extend existing entities, and customize them at runtime. All of these in a clean and simple manner, if you are willing to do so. It doesn’t even matter if those entities don’t have a table representation. You can do that by leveraging C# partial classes and methods. Extending EF Core DbContext is a common scenario, but I think we’re often not aware of its real power.

The way I like to organize entities in my projects

Introducing OnModelCreatingPartial

Commonly your application context will be similar to this: a lot of DbSet that map to the database table object.

    public partial class ConferenceContext : DbContext
    {
        public ConferenceContext(DbContextOptions<ConferenceContext> options)
            : base(options)
        {
            this.Database.EnsureCreated();

        }

        public DbSet<Speaker> Speakers { get; set; }
        public DbSet<Talk> Talks { get; set; }

        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            OnModelCreatingPartial(modelBuilder);
        }

        partial void OnModelCreatingPartial(ModelBuilder modelBuilder);
    }

You might notice the OnModelCreatingPartial method in the example above. I’ve noticed this recently after using a database-first approach in a small project. To be honest, it was really an “Aha!” moment, because if you look into DbContext class source, you will not find a reference to it.

This method gives you a simple and clean way to hook into OnModelCreating method to add customization for the extra-entities you might need.

If you are like me you keep an eye on performance or data transfer from the database into the project, you will use raw SQL queries. As a result, you will end up with many classes used only for specific scenarios.

Before EF Core 3.0 there was another datatype DbQuery that allowed you to specify that the entity T is used only for querying and not for inserts or other operations. Migrations and idempotent scriptsgenerated are done in the same way, but above EF Core 3.0, everything is a DBSet.

It is up to you to tell EF Core that T has no key, like in the example below. You can read more about keyless entity types and the future of this in the Microsoft docs. As you see. extending EF Core DbContext is easy and you can use the approach you are comfortable with either with FluentApi or annotations.

    public partial class ConferenceContext
    {
        public DbSet<TicketSummary> TicketSummaries { get; set; }

        public void OnModelCreatingPartial(ModelBuilder modelBuilder)
        {
            modelBuilder.Entity<TicketSummary>().HasNoKey();

        }
    }

In this example, TicketSummary class is used to retrieve results from a raw SQL query. In that query, I make a join and cherry-pick a few columns. That is it. I have no such table called TicketSummary in my database. Instead, I used FluentApito specify that there is no key for the entity.

The post Extending EF Core DbContext appeared first on Irina Scurtu.

Versioning REST APIs

Irina Scurtu — Fri, 24 Apr 2020 16:13:06 +0000

Headers or URL?

In the context of REST APIs there is a lot of confusion around versioning. Some people recommend versioning REST APIs by adding the version in the URL. Others don’t version at all, and others recommend versioning REST APIs using headers.
Nothing bad so far, but I’ve personally seen a lot of different APIs, that serve different domains and purposes that have a v1 in the URL. Not that is very bad, but the same APIs reach their end of life, with the same v1 in the URL. It’s hard to believe that was no change there since their inception. If so, why add a version in the first place?

I think that these APIs end up with having the v1 forever because the consumer apps are also controlled by the same organization or teams.

This way, the teams just go and change the consumer apps to accommodate the API changes, and that is it. They don’t have to worry about breaking something, somewhere, because they know and have full ownership over those changes.

But what if you would have and API exposed for consumers and you have no control over the consumer code? Would this change something in terms of having v1 forever embedded in your endpoints? For sure it would! You would be forced somehow not to break your consumers, or constrained by some SLAs or legal stuff to ensure backwards compatibility, and to be very transparent about your API changes.

More than than, you will need to ensure that nobody gets hurt by calling your API, and you don’t end up answering to support calls from them. This will make you think about designing your API changes carefully.
Now, let’s see how we can version.

The usual approach to versioning( URL versioning)

The most common approach to versioning is through URLs. You have our endpoints in a form that includes a version like: https://myapp.com/api/v1/speakers.
In order to call anything from there, you need to add v1 and you are done.
If you are talking .NET and WEB API, is very easy to do that for every endpoint just by decorating the Controller with that version, and you are all set.

[Route("api/v1/speakers")]

The inventor of REST - Roy Fielding said in a tweet that:

REST should imply evolvability

If you correlate this with what Tim Berners-Lee said then you might have no reason to version in URL. Not in the path anyways.

COOL URIs don’t change
Tim Berners-Lee, 1998

Why not change the URLS?

Think about it. Sometimes you navigate to websites and you know the URL by heart. URLs matters for SEO, need to be discoverable, express intent and describe the content.
If you suddenly decide to reorganize a website, and you go around and change everything in terms of URLs there a big chance to lose users. Their bookmarks won’t work anymore, and they won’t be able to find the content they are interested in. That’s when people usually give up and move on and forget about you.

If you decide(hopefully) to increase the version, you might break all your clients. And remember, you can’t force your clients to move to the new version when you want.
Surely you can’t say: “From now on, all my consumers will use v2”. It is physically impossible, since you don’t have control over them, and each of them has different priorities.

Suddenly, taking everyone on board for the new version becomes a long process. You need to ensure backwards compatibility for who knows how long (read it as forever) and documentation.

More than that, let’s take another scenario. Microservices and data transfer in Microservices with HttpClients. You usually have somewhere the URLs hardcoded, in a JSON or something or even inside libs with that are distributed through some package manager. If you change the URLs, to change the version to v2, you will need to find all those places in your code where you have it ‘hardcoded’. PS: you know you forget all the places.
Versioning your REST API in URL, to me is not the best idea.

Versioning trough headers

Now I know is not the most common way to do versioning but is my personal preference. Why? “Because cool URIs don’t change”.
Adding meaning and some kind of specificity to a request can be done in different ways, why do it through the URL itself. The URL should be self-describing, don’t pollute that with versioning-related pieces.

In my opinion, as long as that endpoint is very clear in terms of naming – is specific enough, gives a clear understanding of what is the resource it is supposed to handle you are all set.

You can add meaning to your requests very easily. You can add proper verbs, custom headers, to hydrate the request, to specify intent. Remember that a request should be understood in isolation, and HTTP is stateless.
This way you help a bit with content negotiation.
You add Accept header property to help the server understand what the client needs and expects, Content-Type to describe the request body, and so on.

In the same manner, you can add a custom header property that specifies what is the version that the client wants to call.

Using a library

Luckily there is an awesome library in .NET called Microsoft.AspNetCore.Mvc.Versioning that will speed up a lot of manual work. It will give you a lot of flexibility and config options, and your code won't be a mess.

You will need to configure it in Startup.cs with the behavior you want.

services.AddApiVersioning(o => o.ApiVersionReader =
               new HeaderApiVersionReader("api-version"));

Then, you can go ahead and decorate the controllers with the right API version attribute.

[Route("api/speakers")]
    [ApiController]
    [ApiVersion("1.0")]
    public class SpeakersController : ControllerBase
    {
        //code removed for brevity
    }

Using simple attributes, you are now allowed to have 2 controllers side by side, that have the same route. One of them has the previous version, and the second the new version. Using the same URL and without any changes will respond correctly to requests, as long as the correct header is specified in the request.

    [Route("api/speakers")]
    [ApiController]
    [ApiVersion("2.0")]
    public class Speakers2Controller : ControllerBase
    {
    }

When you issue a request to the API, you will need to have api-version header with the correct value specified. api-version:1.0 or api-version : 2.0 Based on that, the request will hit a controller on another.
You are not limited to only this kind of configuration.
You can assume a default version if this header is not there, or you can enforce a query parameter for the version, configure default behavior and error pages, and so on.
Everything is configurable inside Startup.cs

When to increase the version?

There is no clear answer to this. It depends on the number of changes and their magnitude. Be pragmatic about it, and don't take it to the extreme. An API version number is not the build number. Don't do that.
How often do you increase the version number is a matter of API design first. Ask yourself a few questions:

How many consumers you have? In what way are these clients affected by your changes? What is the development speed for your consumers? Are there legal/contract matters? (Maybe they don't have the same agility as you have)
Is it easy for you to maintain multiple versions of the same API?

In conclusion

Versioning REST APIs is not that hard, and REST itself is not bad. There is a certain amount of discipline to do this. You need to design the API with your consumers/clients in mind and take responsibility when you introduce changes.

If you find this intriguing, ping me on twitter. Let's chat!

View Razor changes without building the project

Irina Scurtu — Sun, 05 Apr 2020 12:54:21 +0000

How to view Razor changes without building the project. There is no need to build the project to see changes in Views.

When I was a junior developer I remember my team lead telling me:

No, you don’t need to rebuild the solution if you modify something views

I’ve absorbed this phrase and kept telling it to my students. Until recently to realize that is not of actuality anymore. For many years after that, I stopped working in ASP MVC projects, having only APIS, angular, and React client apps.

Recently I’ve upgraded an MVC projectfrom 2.2 to 3.1 and needed to make some changes in Views.

Nothing bad so far, I still remembered how it’s done. Yey! It is like riding a bike.

Oddly enough, I had to rebuild the solution to see the changes made in Views and I was really annoyed, I had just static HTML and couldn’t understand why I have to rebuild. Up until this moment, compilation of views was triggered by the editing. I started to dig around and did some research, and here’s what I’ve found out.

Razor compilation is enabled by default only for build/publish

Razor compilation is enabled by default only for the build and publish scenarios, not for runtime aka when you edit the view.

Now, if you want that functionality back, you need to install a NuGet package: Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation and add the middleware and boom, it works.

services.AddControllersWithViews()
        .AddRazorRuntimeCompilation();

Conditional runtime compilation

Another method to obtain the same thing, which I really don’t like is based on directives. This way, you can keep the default mode, but enable what you need only when you are debugging (running locally).

First, you need to start by editing your csproj file to add a condition on the package.

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"

Version="3.1.3" Condition="'$(Configuration)' == 'Debug'" />

After that, you need to make some adjustments in your startup file to add the condition. Start by adding a property to hold IWebHostEnvironment, and set the value from the controller.

  public Startup(IConfiguration configuration, IWebHostEnvironment env)
        {
            Configuration = configuration;
            HostEnvironment = env;
        }

        public IConfiguration Configuration { get; set; }

        public IWebHostEnvironment HostEnvironment { get; }

After you did that you need to add the #if condition to enable the ‘dynamic’ loading for the conditional runtime compilation

            var builder = services.AddControllersWithViews();
#if DEBUG
            if (HostEnvironment.IsDevelopment())
            {
                builder.AddRazorRuntimeCompilation();
            }
#endif

With this in mind, make sure you change the IWebHostEnviroment scattered around your Startup class, and point it to the newly introduced property. Is not the cleanest solution, I do not prefer this, but it does the job. More than that, we all lie to ourselves that, ok, I’m gonna change the default, and just comment the line of code before deploying. Only this will never happen.

In the official docs, they say that by using the conditional compilation you make sure that the published output uses the compiled views, are smaller in size, and it doesn’t enable file watchers in production. All these might be true, but it doesn’t make my developer experience nicer. What do you think?

The post View Razor changes without building the project appeared first on Irina Scurtu.

From .NET 2.2 to 3.1 – Routing issues

Irina Scurtu — Mon, 30 Mar 2020 18:10:32 +0000

Having a website on 2.2, I thought that there is about the case to upgrade. Now or never I said. How hard can it be?

I went pretty smooth, by using the -> migration guide..until…. I’ve bumped into routing. I’ve spent a decent amount of time trying to debug the issue, without visible progress.

My issue was that my website had a public side and an Admin area where all the administration magic happens after login.

Changing from app.AddMvc() to app.UseEndpoints() is pretty easy just by changing this:

app.UseMvc(routes =>     {          routes.MapRoute(             name: "areaRoute year",             template: "{area:exists}/{controller}/{action}/{id?}",             defaults: new { controller = "Home", action = "Index" }             );}});

to this:

app.UseEndpoints(endpoints =>{    endpoints.MapControllerRoute(        name: "areaRoute year",        pattern: "{area:exists}/{controller}/{action}/{id?}",        defaults: new {controller = "Home", action = "Index"}    );});

So the real changes in here are the template parameter name to pattern, and MapRouteto MapControllerRoute and the rest is pretty much the same.

So far so good, but my routes on the Admin area simply didn’t work anymore. Everything on the admin was not accessible, and I got 404 in the browser. This led me to believe that my routes had an issue around authorization. I tried again and failed again, and I gave up.

Fortunately, we still have the option to ignore for now the UseEndpoints and fallback to the old version by setting a single property to false in ConfigureServices.

services.AddMvc(options => options.EnableEndpointRouting = false);

Now, by setting this you can use the old approach without any issues, just make sure you don’t add the app.UseRouting() by any means.

Take 2 – try again

Renamed everything as it should be and looked a bit at the order of Midleware imports.

I can say that 3.1 middleware order matters even more than before. You must have

 app.UseRouting();
 //anything in between
 app.UseAuthentication();
 app.UseAuthorization();
 app.UseEndpoints(endpoints =>...);

My actual issue was that app.UseAuthentication() and app.UseAuthorization() order was reversed. I can’t tell you why it worked in 2.2, but for sure doesn’t work anymore in 3.1.

After this fix, I was able to have a fully working app migrated to 3.1, and now I use endpoints not routes.

Conclusion

We knew that order of the middlewares matters, but in this case there is a slight difference. Make sure you have .UseRouting(), any other middleware you need and then UseAuthentication, UseAuthorization, UseEndpoints

The post From .NET 2.2 to 3.1 – Routing issues appeared first on Irina Scurtu.