Entity Framework Core - Add, Remove, Attach and Update

In this post I will explain how the Add / Remove / Attach and Update affects the EntityState and how Entiy Framework behaves based on each state.

Before we start talking about the differences of each of the methods above is important to understand the five different states defined by Entity Framework.

Entity states

These states are defined in the EntityState Enum, see below the description of each one:

• Added: the entity is being tracked by the context but does not yet exist in the database
• Unchanged: the entity is being tracked by the context and exists in the database, and its property values have not changed from the values in the database
• Modified: the entity is being tracked by the context and exists in the database, and some or all of its property values have been modified
• Deleted: the entity is being tracked by the context and exists in the database, but has been marked for deletion from the database the next time SaveChanges is called
• Detached: the entity is not being tracked by the context

SaveChanges

The SaveChanges method will work in different ways based on the EntityState.

See below the behavior for each EntityState:

• Unchanged entities are not touched by SaveChanges. Updates are not sent to the database for entities in the Unchanged state.
• Added entities are inserted into the database and then become Unchanged when SaveChanges returns.
• Modified entities are updated in the database and then become Unchanged when SaveChanges returns.
• Deleted entities are deleted from the database and are then detached from the context.

Add, Remove, Attach and Update

Now that we now the Entity Framework EntityStates and how the SaveChanges work with each state will be easy to understand how the methods Add / Remove / Attach and Update works.

Add

The Add method will add the object to the context, which means that the object will start being tracked by Entity Framework and its Entity State will be EntityState.Added.

Once SaveChanges is called a new record will be added to the database.

See below the Entity State in the Immediate Window:

Attach

The Attach method will add the object to the context, which means that the object will start being tracked by Entity Framework and its Entity State will be EntityState.Unchanged.

Once SaveChanges is called  Entity framework won`t touch this object.


See below the Entity State in the Immediate Window:

Remove

The Remove method will add the object to the context, which means that the object will start being tracked by Entity Framework and its Entity State will be EntityState.Removed.

Once SaveChanges is called  Entity framework will delete the record from the database.

See below the Entity State in the Immediate Window:

Update

The Update method will add the object to the context, which means that the object will start being tracked by Entity Framework and its Entity State will be EntityState.Modified.

Once SaveChanges is called, Entity framework will update the record in the database.

See below the Entity State in the Immediate Window:

Conclusion

As we can see all the four methods above will tell Entity Framework to start tracking the objects, but each of them will set different States to the entity and then Entity framework will execute a different operation in the database when SaveChanges is called.

Understanding ASP.NET Middleware

In ASP.NET Core, middleware is the term used for components that form the Request Pipeline.

The pipeline request is like a chain, which can contain multiple middlewares. These components will handle the request in sequence; each component will inspect the request and decide whether it should be passed to the next middleware or just generate a response interrupting the chain.

Once the request has been handled a response will be generated and send back to the client passing along the chain.

Execution Order

Middlewares will execute in the same order they are registered when handling requests and in the reverse order when handling responses.

Check the example below:

How to create a Middleware

Middleware components don`t implement interfaces or derive from classes, It simply has a constructor that takes RequestDelegate as parameter and implements the Invoke Method.

The RequestDelegate represents the next Middleware component of the chain and the Invoke method is called when the component receives a request.

Next I will show a few examples.

Creating Content-Generating Middleware

The most important type of middleware generates content for clients, and it is this category to which MVC belongs.

This kind of middleware is used when you want to generate some content and send it back to the client without the need of dealing with all the MVC complexity.

Check the implementation below:

    public class ContentMiddleware

    {

        private RequestDelegate nextDelegate;

        public ContentMiddleware(RequestDelegate next) => nextDelegate = next;

        public async Task Invoke(HttpContext httpContext)

        {

            if (httpContext.Request.Path.ToString().ToLower() == "/content-middleware")

            {

                await httpContext.Response.WriteAsync(

                "This content was generated by the middleware", Encoding.UTF8);

            }

            else

            {

                await nextDelegate.Invoke(httpContext);

            }

        }

    }

Creating Short-Circuiting Middleware

Short-Circuiting Middleware Components are used when you want to inspect the request and decide if the request should be passed to next component or not.

The example below is checking if it the request contains the User-Id header, if not the middleware will break the chain and return a 401-Unauthorized response to the client.

    public class ShortCircuitMiddleware

    {

        private RequestDelegate nextDelegate;

        public ShortCircuitMiddleware(RequestDelegate next) => nextDelegate = next;

        public async Task Invoke(HttpContext httpContext)

        {

            if (!httpContext.Request.Headers["User-Id"].Any())

            {

                httpContext.Response.StatusCode = (int)HttpStatusCode.Unauthorized;

            }

            else

            {

                await nextDelegate.Invoke(httpContext);

            }

        }

    }

Creating Request-Editing Middleware

The next type of middleware component examined doesn’t generate a response. Instead, it changes requests before they reach other components later in the chain. This kind of middleware is mainly used for platform integration to enrich the ASP.NET Core representation of an HTTP request with platform-specific features.

The example below will check if the request contains a blank User-Id in the header and if yes it will be removed.

 public async Task Invoke(HttpContext httpContext)

        {

            if (httpContext.Request.Headers["User-Id"].Any() &&

                string.IsNullOrWhiteSpace(httpContext.Request.Headers["User-Id"].ToString()))

            {

                httpContext.Request.Headers.Remove("User-Id");

            }

            else

            {

                await nextDelegate.Invoke(httpContext);

            }

        }

Interacting with another Middleware

Middleware components can interact with each other, let`s consider that RequestEditMiddleware is executed before the ShortCircuitMiddleware.

In that case if a request contains blank User-Id Header the RequestEditMiddleware will remove that header from the request and call the next component, which is the ShortCircuitMiddleware, the ShortCircuitMiddleware won`t find the header User-Id and will break the chain returning a 401 response to the client.

Registering a Middleware

Now that we already know how to create our own custom components, how do we use it?

It`s simple, in the Startup class there is a method called Configured which is responsible to setup how the application will handle requests.

This method has a parameter of type IApplicationBuilder, that is the object we use to register our components.

See example below:

       public void Configure(IApplicationBuilder app, IHostingEnvironment env)

        {

            app.UseMiddleware<ContentMiddleware>();

            app.UseMiddleware<RequestEditMiddleware>();

            app.UseMiddleware<ShortCircuitMiddleware>();

            app.UseHttpsRedirection();

            app.UseMvc();

        }

There is a more elegant way to register the components, for that we need to create some extension methods.

See below:

  public static class MiddlewareExtensions

    {

        public static IApplicationBuilder UseContentMiddleware(this IApplicationBuilder app)

        {

            return app.UseMiddleware<ContentMiddleware>();

        }

        public static IApplicationBuilder UseRequestEditMiddleware(this IApplicationBuilder app)

        {

            return app.UseMiddleware<RequestEditMiddleware>();

        }

        public static IApplicationBuilder UseShortCircuitMiddleware(this IApplicationBuilder app)

        {

            return app.UseMiddleware<ShortCircuitMiddleware>();

        }

    }

After creating the extension methods all we have to do is register the components using it.

public void ConfigureDevelopment(IApplicationBuilder app, IHostingEnvironment env)

        {

            app.UseContentMiddleware();

            app.UseRequestEditMiddleware();

            app.UseShortCircuitMiddleware();

            app.UseHttpsRedirection();

            app.UseMvc();

        }

RESTful API Designing guidelines

What is REST?

Representational state transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style, called RESTful Web services, provide interoperability between computer systems on the Internet.

Terminologies

The following are the most important terms related to REST APIs

Resource

Resource is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it.

E.G Company

Collections

Collections are set of resources.

E.G Companies is the collection of the Company Resource

URL

URL (Uniform Resource Locator) is a path through which a resource can be located and some actions can be performed on it.

API Endpoint

In simple terms, an API endpoint is the point of entry in a communication channel when two systems are interacting.

It refers to touchpoints of the communication between an API and a server.

The location where the API sends a request and where the response emanates is what is known as an endpoint.

API vs Endpoint

An API refers to a set of protocols and tools that allow interaction between two different applications. In simple terms, it is a technique that enables third-party vendors to write programs that can easily interface with each other. 

On the other hand, an endpoint is the place of interaction between applications. API refers to the whole set of protocols that allows communication between two systems while an endpoint is a URL that enables the API to gain access to resources on a server.

Web Api Endpoint Naming Convention

Methods Naming Convention

In OOP methods are named with verbs to make it easier to identify what operation that method will perform, for example the method GetEmployees(int departmentID) will return all the employees that belongs to a department.

Should we use the same naming convention when designing web apis endpoints?

The answer is NO.

Web Api endpoints must be names with NOUNS instead of verbs and it should contain the plural form of the Resource the api will perform operations on.

Example: https://www.estradaci.com/apis/v1/Employees

If the URL can`t contain verbs, how do we know which action will be performed?

HTTP Verbs will be responsible for telling which action the WEB API should perform.

Let`s look at the most used HTTP Verbs used while creating WEB APIs.

HTTP VERBS

GET

Use GET requests to retrieve resource representation/information only – and not to modify it in any way. As GET requests do not change the state of the resource, these are said to be safe methods. 

Additionally, GET APIs should be idempotent, which means that making multiple identical requests must produce the same result every time until another API (POST or PUT) has changed the state of the resource on the server.

Examples:

GET https://www.estradaci.com/apis/v1/Employees

GET https://www.estradaci.com/apis/v1/Employees/1

GET https://www.estradaci.com/apis/v1/Employees?name=Jeff

All the endpoints above will fetch employees but using different inputs to query the employees.

HTTP POST

Use POST APIs to create new subordinate resources, e.g. a file is subordinate to a directory containing it or a row is subordinate to a database table. Talking strictly in terms of REST, POST methods are used to create a new resource into the collection of resources.

Examples:

POST https://www.estradaci.com/apis/v1/Employees

POST https://www.estradaci.com/apis/v1/Employees/Address

Both endpoints above will insert data in the database, the first one will create a new employee and the second one will create an address for an employee.

HTTP PUT

Use PUT APIs primarily to update existing resource (if the resource does not exist then API may decide to create a new resource or not). If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

Examples:

PUT https://www.sampleapis.com/apis/v1/Employees

PUT https://www.sampleapis.com/apis/v1/Employees/Address

Both endpoints above will update data in the database, the first one will update an employee and the second one will update the employee`s address.

HTTP DELETE

As the name applies, DELETE APIs are used to delete resources (identified by the Request-URI).

Examples:

DELETE https://www.sampleapis.com/apis/v1/Employees

DELETE https://www.sampleapis.com/apis/v1/Employees/Address

Both endpoints above will delete data from the database, the first one will delete an employee and the second one will delete the employee`s address.

As we can see the same URL can perform different actions when requested with different HTTP Verbs.

For example the https://www.sampleapis.com/apis/v1/Employees can Get, Create, Update and Delete employees based on the HTTP Verb used.

HTTP response status codes

When the client sends the request to the server it expects a response indicating the result of the operation.

It`s a good practice to return coherent status codes to make it easy to the client understand what happened when the request is processed.

HTTP defines standard status codes that can be used to convey the results of a client’s request. The status codes are divided into the five categories presented below.

CATEGORY	DESCRIPTION
1xx: Informational	Communicates transfer protocol-level information.
2xx: Success	Indicates that the client’s request was accepted successfully.
3xx: Redirection	Indicates that the client must take some additional action in order to complete their request.
4xx: Client Error	This category of error status codes points the finger at clients.
5xx: Server Error	The server takes responsibility for these error status codes.

Check below the description of the most used Status Codes used when creating a web api.

For a complete list of the HTTP Status Codes check https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=netframework-4.8

200 (OK)

It indicates that the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate.

201 (Created)

A REST API responds with the 201 status code whenever a resource is created inside a collection. There may also be times when a new resource is created as a result of some controller action, in which case 201 would also be an appropriate response.

204 (No Content)

The 204 status code is usually sent out in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the response message’s body.

An API may also send 204 in conjunction with a GET request to indicate that the requested resource exists, but has no state representation to include in the body.

304 (Not Modified)

This status code is similar to 204 (“No Content”) in that the response body must be empty. 

The key distinction is that 204 is used when there is nothing to send in the body, whereas 304 is used when the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match.

400 (Bad Request)

400 is the generic client-side error status, used when no other 4xx error code is appropriate. Errors can be like malformed request syntax, invalid request message parameters, or deceptive request routing etc.

The client SHOULD NOT repeat the request without modifications.

401 (Unauthorized)

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all.

404 (Not Found)

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource but may be available in the future. Subsequent requests by the client are permissible.

500 (Internal Server Error)

500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.

Content Negotiation

When sending a request to an API we need to tell the server what is the type of the data we are sending and the server is responsible to tell the client the same.

At server side, an incoming request may have an entity attached to it. To determine it’s type, server uses the HTTP request header Content-Type. Some common examples of content types are “text/plain”, “application/xml”, “text/html”, “application/json”, “image/gif”, and “image/jpeg”.

Content-Type: application/json

Similarly, to determine what type of representation is desired at client side, HTTP header ACCEPT is used. It will have one of the values as mentioned for Content-Type above.

Accept: application/json

The most used content-type used by APIS to represent the object the is being sent to the server or returned to the client is JSON, make sure to use the camelCase naming convention when using JSON.

API Versioning

One of the most important things in WEB API development is the versioning.

WEB APIs must be well versioned in order to prevent the clients that are consuming it to break.

When a Break Change is made to an existing WEB API, instead of modifying the existing one we must create a new version of it.

For example:

Several changes are required to be made on the WEB API https://www.sampleapis.com/apis/v1/Employees and these changes may lead the consumers to break their integrations.

Instead of simply applying the changes to this API we need to create a new version of the api,  E.G https://www.sampleapis.com/apis/v2/Employees.

This will prevent the clients that are consuming the V1 to break and will give them the time and flexibility to migrate their calls to the V2.