View source for Dotnet api linux

= Set up with VS Code =
== Create Project ==
To create a webapi using .net core 3.1 simply type
<syntaxhighlight lang="bash">
dotnet new webapi
</syntaxhighlight>
== Restore Nuget Packages ==
<syntaxhighlight lang="bash">
dotnet add package Microsoft.EntityFrameworkCore
</syntaxhighlight>
== Install Migration Tool ==
Exercise called for using Add-Migration on windows. In Linux this translates to
<syntaxhighlight lang="bash">
# Install Tool
dotnet add package Microsoft.EntityFrameworkCore.Tools.Dotnet
# Install dotnet-ef
dotnet tool install --global dotnet-ef
# Run Migration Creation
dotnet ef migrations add InitialCreate
</syntaxhighlight>

Install SQL Server
<syntaxhighlight lang="bash">
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -

# Add to /etc/apt/source.list
# deb [arch=amd64,arm64,armhf] https://packages.microsoft.com/ubuntu/18.04/mssql-server-2019 bionic main

sudo apt-get update
sudo apt-get install -y mssql-server
sudo /opt/mssql/bin/mssql-conf setup

# Show working
systemctl status mssql-server --no-pager
</syntaxhighlight>

Create user
<syntaxhighlight lang="bash">

CREATE DATABASE test;
GO

CREATE LOGIN test with PASSWORD = 'guess!';
GO

EXEC master..sp_addsrvrolemember @loginame = N'test', @rolename = N'dbcreator'
GO
</syntaxhighlight>

== Running Query ==
List tables in DB 
<syntaxhighlight lang="SQL">
select schema_name(t.schema_id) as schema_name,
       t.name as table_name,
       t.create_date,
       t.modify_date
from sys.tables t
order by schema_name,
         table_name;
</syntaxhighlight>

<syntaxhighlight lang="bash">
sqlcmd -S localhost -U test -d CourseLibraryDB -Q list_tables.sql 
</syntaxhighlight>

= Structuring and Implementing =
== Interacting with Resources through HTTP Methods ==
Below is a table which shows the methods and how they work with the Authors and Courses demo app along with suggested naming. Note the use of nouns

[[File:Http methods rest.png]]

== Content Negotiation ==
We also need to ensure that we configure what type of media we support. In ASP .net this can be done by setting the setupAction. This will stop the default of json being returned.

<syntaxhighlight lang="c#">

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers(setupAction => {
                setupAction.ReturnHttpNotAcceptable = true;
            }).AddXmlDataContractSerializerFormatters();
...
</syntaxhighlight>

==Method Safety and Method Idempotency==
Method safety and idempotency help decide which method to use for which use case.
[[File:Method safety idempotency.png]]

= Getting Resources =
== Intro ==
When we get resources we generally expect business objects rather than entities. These are known as DTOs (Data Transfer Objects). For C# there are other options but automapper product seems to be the product of choice for ASP .NET. 
== Adding Automapper ==
To add automapper
<syntaxhighlight lang="bash">
dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection
</syntaxhighlight> 
== Configure Automapper ==
And configure the service in the code
<syntaxhighlight lang="c#">

        public void ConfigureServices(IServiceCollection services)
        {
...
            services.AddAutoMapper(AppDomain.CurrentDomain.GetAssemblies());
...
</syntaxhighlight>
== Create a DTO Class ==
<syntaxhighlight lang="c#">
    public class AuthorDto
    {
        public Guid Id { get; set; }

        public string Name { get; set; }

        public int Age { get; set; }

        public string MainCategory { get; set; }
    }
</syntaxhighlight>

== Create a Profile Class ==
This class performs the mapping from the Entity to the DTO
<syntaxhighlight lang="c#">
public class AuthorsProfile : Profile
{
    public AuthorsProfile()
    {
        CreateMap<Entities.Author, Models.AuthorDto>()
            .ForMember(
               dest => dest.Name,
               opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
            .ForMember(
               dest => dest.Age,
               opt => opt.MapFrom(src => src.DateOfBirth.GetCurrentAge()));
        }
    }
}
</syntaxhighlight>

== Implement the Get of collection and instance on the controller ==

<syntaxhighlight lang="c#">
...
        [HttpGet()]
        public ActionResult<IEnumerable<AuthorDto>> GetAuthors()
        {
            var authorsFromRepo = _courseLibraryRepository.GetAuthors();
            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo));
        }
        [HttpGet("{authorId}")]
        public IActionResult GetAuthor(Guid authorId)
        {
            var authorsFromRepo = _courseLibraryRepository.GetAuthor(authorId);
            if (authorsFromRepo == null)
            {
                return NotFound();
            }
            return Ok(_mapper.Map<AuthorDto>(authorsFromRepo));
        }
</syntaxhighlight>

== Overriding Exception Errors ==
To control the error the consumer sees in the case of an exception, configure an exception handler in Startup.cs
<syntaxhighlight lang="c#">
...
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler(appBuilder => {
                    appBuilder.Run(async context => {
                        context.Response.StatusCode = 500;
                        await context.Response.WriteAsync("An unexpected fault occurred. Please try again");
                    });
                });
            }
</syntaxhighlight>
== Supporting HEAD ==
To support just sending the result without the body simply add HttpHead to the getters.
<syntaxhighlight lang="c#">
        [HttpGet()]
        [HttpHead]
        public ActionResult<IEnumerable<AuthorDto>> GetAuthors()
        {
            var authorsFromRepo = _courseLibraryRepository.GetAuthors();
            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo));
        }
</syntaxhighlight>
=Filtering And Searching =
==Bindings==
To get the arguments for filtering and search ASP .NET uses the following
*[FromQuery] - Gets values from the query string.
*[FromRoute] - Gets values from route data.
*[FromForm] - Gets values from posted form fields.
*[FromBody] - Gets values from the request body.
*[FromHeader] - Gets values from HTTP headers.
==Filtering ==
Basically add an argument to the get method and implement it on the data repository checking for an argument and returning appropriately. Note the default [FromQuery] argument is the key to this being passed. E.g. mainCategory=Rum on the URI
<syntaxhighlight lang="c#">
# In the controller
        [HttpGet()]
        [HttpHead]
        public ActionResult<IEnumerable<AuthorDto>> GetAuthors(string mainCategory)
        {
            var authorsFromRepo = _courseLibraryRepository.GetAuthors(mainCategory);
            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo));
        }

# In the Repository
        public IEnumerable<Author> GetAuthors(string mainCategory)
        {
            if (string.IsNullOrEmpty(mainCategory)) return _context.Authors.ToList<Author>();
            return _context.Authors.Where(x => x.MainCategory == mainCategory.Trim()).ToList();
        }
</syntaxhighlight>
==Searching==
To implement this just add a parameter for the searching as you did for filtering and implement appropriately
<syntaxhighlight lang="c#">
        public IEnumerable<Author> GetAuthors(string mainCategory, string searchQuery)
        {
            if (string.IsNullOrEmpty(mainCategory) && string.IsNullOrEmpty(searchQuery)) return _context.Authors.ToList<Author>();

            var collection = _context.Authors as IQueryable<Author>;

            if (!string.IsNullOrEmpty(mainCategory))
            {
                collection = collection.Where(x => x.MainCategory == mainCategory.Trim());
            }

            if (!string.IsNullOrEmpty(searchQuery))
            {
                collection = collection.Where(
                    x => x.MainCategory.Contains(searchQuery.Trim()) ||
                         x.FirstName.Contains(searchQuery.Trim()) ||
                         x.LastName.Contains(searchQuery.Trim()));
            }

            return collection.ToList();
        }
</syntaxhighlight>

==Combining Parameters==
Make a class to contain these and pass them to the repository. 
<syntaxhighlight lang="c#">
    public class AuthorsResourceParameters
    {
        public string MainCategory { get; set; }
        public string SearchQuery { get; set; }

    }
</syntaxhighlight>
You will need to tell the controller where to find them as it is not the default. i.e.
<syntaxhighlight lang="c#">
        [HttpGet()]
        [HttpHead]
        public ActionResult<IEnumerable<AuthorDto>> GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
            var authorsFromRepo = _courseLibraryRepository.GetAuthors(authorsResourceParameters);
            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo));
        }

</syntaxhighlight>

= Creating Resources=
==Create a DTO for creations==
<syntaxhighlight lang="c#">
    public class AuthorForCreationDto
    {
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public DateTimeOffset DateOfBirth { get; set; }
        public string MainCategory { get; set; }
    }
</syntaxhighlight>

==Create a profile==
This converts the DTO to an entity
<syntaxhighlight lang="c#">
    public class AuthorsProfile : Profile
    {
       CreateMap<Models.AuthorForCreationDto, API.Entities.Author>();
    }
</syntaxhighlight>
==Implement Post==
Add a name to your GET for your entity
<syntaxhighlight lang="c#">
        [HttpGet("{authorId}", Name="GetAuthor")]
        public IActionResult GetAuthor(Guid authorId)
        {
...
        }
</syntaxhighlight>
Most of the code is simple except for the CreateAtRoute. This is used to add a Location header to the response. The Location header specifies the URI of the newly created item.
<syntaxhighlight lang="c#">
        [HttpPost]
        public ActionResult<AuthorDto> CreateAuthor(AuthorForCreationDto author)
        {
            var authorEntity = _mapper.Map<Author>(author);
            _courseLibraryRepository.AddAuthor(authorEntity);
            _courseLibraryRepository.Save();

            var authorToReturn = _mapper.Map<AuthorDto>(authorEntity);

            return CreatedAtRoute("GetAuthor",        // the name of the route
                new { authorId = authorToReturn.Id }, // the parameters of the route
                authorToReturn);                      // the DTO to create the DTO from
        }
</syntaxhighlight>

== Creating Resources For a Collection ==
This is the same as above with the exception of the Location header. If you are creating a collection then the location header will need to support the retrieval of the collection post creation.

=== Creating the Post Collection Request ===
This is identical to the single request but using an array.
<syntaxhighlight lang="c#">
[HttpPost]
        public ActionResult<IEnumerable<AuthorDto>> CreateAuthorCollections(IEnumerable<AuthorForCreationDto> authorCollection)
        {
            var authorEntities = _mapper.Map<IEnumerable<Author>>(authorCollection);
            foreach (var author in authorEntities)
            {
                _courseLibraryRepository.AddAuthor(author);
            }
            _courseLibraryRepository.Save();

            var authorCollectionToReturn = _mapper.Map<IEnumerable<AuthorDto>>(authorEntities);

            return CreatedAtRoute("GetAuthorCollection",
                new { authorId = string.Join(",", authorCollectionToReturn.Select(x => x.Id)) },
                authorCollectionToReturn);
        }
</syntaxhighlight>

=== Creating the Get Collection Request ===
Everything is the same except you need a [FromRoute] and a ModelBinder. The model binder needs to create and array of composite keys so that all of the items can be retrieved.
<syntaxhighlight lang="c#">
        [HttpGet("({authorIds})", Name = "GetAuthorCollection")]
        public IActionResult GetAuthorCollection(
            [FromRoute]
            [ModelBinder(BinderType = typeof(ArrayModelBinder))] IEnumerable<Guid> authorIds)
        {
            if (authorIds == null)
            {
                return BadRequest();
            }

            var authorsFromRepo = _courseLibraryRepository.GetAuthors(authorIds);

            if (authorIds.Count() != authorsFromRepo.Count())
            {
                return NotFound();
            }

            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo));
        }

</syntaxhighlight>

=== Creating Array Model Binder ===
==== What is Model Binding ====
What is Model binding
Controllers and Razor pages work with data that comes from HTTP requests. For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. Model binding automates this process. The model binding system:

Retrieves data from various sources such as route data, form fields, and query strings.
Provides the data to controllers and Razor pages in method parameters and public properties.
Converts string data to .NET types.
Updates properties of complex types.

==== My Example of Model Binding ====
Tried to provide explanation in the comments but basically if checks if sane and then returns an appropriate array of composite keys.

<syntaxhighlight lang="c#">
    public class ArrayModelBinder : IModelBinder
    {
        public Task BindModelAsync(ModelBindingContext bindingContext)
        {
            // Our binder only works on enumerable types
            if(!bindingContext.ModelMetadata.IsEnumerableType)
            {
                bindingContext.Result = ModelBindingResult.Failed();
                return Task.CompletedTask;
            }

            // Get Inputted value from the value provided
            var value = bindingContext.ValueProvider.GetValue(bindingContext.ModelName).ToString();

            // If the value is null or whitespace, we return null
            if(string.IsNullOrWhiteSpace(value))
            {
                bindingContext.Result = ModelBindingResult.Success(null);
                return Task.CompletedTask;
            }
 
            // If the model is enumerable and 
            //    the value isn't null or whitespace
            //       Get the enumerable types and a converter
            var elementType = bindingContext.ModelMetadata.ModelType.GetTypeInfo().GetGenericArguments()[0];


            var elementTypeConvertor =  TypeDescriptor.GetConverter(elementType);

            // Convert each item in the value list to the enumerable type
            var valuesAsStringArray = value.Split( new[] {","}, StringSplitOptions.RemoveEmptyEntries);
            var values = valuesAsStringArray.Select(x=> elementTypeConvertor.ConvertFrom(x.Trim())).ToArray();
            
            // Create an array of the same length received and the element type in the binding context
            var typedValues = Array.CreateInstance(elementType, values.Length);
            // Copy the string values to to the typed values
            values.CopyTo(typedValues,0);
            // Set the model
            bindingContext.Model = typedValues;

            // Return the result
            bindingContext.Result = ModelBindingResult.Success(bindingContext.Model);
            return Task.CompletedTask;
            
        }
    }
</syntaxhighlight>

==Supporting Options==
On our controller we should make sure that the available options are set.
<syntaxhighlight lang="c#">
       [HttpOptions]
        public IActionResult GetAuthorsOptions()
        {
            Response.Headers.Add("Allow", "GET,OPTIONS,POST");
            return Ok();
        }
</syntaxhighlight>
=Validation=
==Intro==
Validations should return the correct status code so the user knows how to respond. ASP has built in responses which do the right thing when implemented. By default if not implemented these may be 500.
==Validation with Data Annotations==
These are provided by the ComponentModel library and you can match the database in your DTOs. E.g.
<syntaxhighlight lang="c#">
    public class CourseForCreationDto
    {
        [Required, ErrorMessage="This is required"]
        [MaxLength(100)]     
        public string Title { get; set; }

        [MaxLength(1500)]        
        public string Description { get; set; }
    }
}
</syntaxhighlight>

==Validation at Class level==
You can implement this using the IValidatableObject interface. Note this does not run by default if the Data Annotations fail.
<syntaxhighlight lang="c#">
    public class CourseForCreationDto : IValidatableObject
    {
...
        public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
        {
            if (Title == Description)
            {
                yield return new ValidationResult(
                "The provided description should be different from the title.",
                new[] { "CoursesForCreationDta" });
            }
        }    
    }
</syntaxhighlight>

==Custom Validation at Class level==
We can separate the validation into a class and use a decorator to do the same job. i.e. putting [CourseTitleMustBeDifferentFromDescriptionAttribute] against the class.
<syntaxhighlight lang="c#">
    public class CourseTitleMustBeDifferentFromDescriptionAttribute : ValidationAttribute
    {
        protected override ValidationResult IsValid(object value, ValidationContext validationContext)
        {
            var course = (CourseForCreationDto)validationContext.ObjectInstance;

            if (course.Title == course.Description)
            {
                return new ValidationResult(
                "The provided description should be different from the title.",
                new[] { "CoursesForCreationDta" });
            }

            return ValidationResult.Success;
        }
    }
</syntaxhighlight>
==Customising the validation error responses==
This probably needs revisiting. I think we need to make sure the problem details are appropriate for the audience. Here is the example provided.
<syntaxhighlight lang="c#">
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers(setupAction =>
            {
                setupAction.ReturnHttpNotAcceptable = true;
            }).AddXmlDataContractSerializerFormatters().ConfigureApiBehaviorOptions(
                setupAction =>
                {
                    setupAction.InvalidModelStateResponseFactory = context =>
                    {
                        // Create problem details object
                        var problemDetailsFactory = context.HttpContext.RequestServices.GetRequiredService<ProblemDetailsFactory>();
                        var problemDetails = problemDetailsFactory.CreateValidationProblemDetails(
                            context.HttpContext,
                            context.ModelState);

                        // Add addtional information
                        problemDetails.Detail = "See the errors field for details";
                        problemDetails.Instance = context.HttpContext.Request.Path;

                        var actionExecutingContext = context as Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext;
                        // If error count > 0
                        // and all arguments were found and parsed
                        //    This is a validation error
                        if (context.ModelState.ErrorCount > 0 &&
                           actionExecutingContext?.ActionArguments.Count == context.ActionDescriptor.Parameters.Count)
                        {
                            problemDetails.Type = "https://courselibrary.com/modelvalidationerror";
                            problemDetails.Status = StatusCodes.Status422UnprocessableEntity;
                            problemDetails.Title = "One or more validation errors occurred";

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

                        // If one of the arguments was not found or could not be parsed
                        //    This is bad input
                        problemDetails.Status = StatusCodes.Status400BadRequest;
                        problemDetails.Title = "One or more errors on input occurred";
                        return new UnprocessableEntityObjectResult(problemDetails)
                        {
                            ContentTypes = { "application/problem+json" }
                        };

                    };
                });
...
</syntaxhighlight>
== FluentValidation ==
This was a library recommended on the course.

=Updating Resources=
==Using PUT==
This is almost identical to post but does not require you to return content. The Automapper is handy to do the DTO->Entity->DTO 
<syntaxhighlight lang="c#">
        [HttpPut("{courseId}")]
        public ActionResult UpdateCourse(Guid authorId, Guid courseId, CourseForUpdateDto course)
        {
            if (_courseLibraryRepository.AuthorExists(authorId) == false) return NotFound();

            var courseForAuthorFromRepo = _courseLibraryRepository.GetCourse(authorId, courseId);
            if (courseForAuthorFromRepo == null) return NotFound();

            // map the entity to the courseForUpdate
            // apply the updated field values to that dto
            // map the CourseForUpdateDto back to an entity
            _mapper.Map(course, courseForAuthorFromRepo);

            _courseLibraryRepository.UpdateCourse(courseForAuthorFromRepo);
            _courseLibraryRepository.Save();

            return NoContent();
        }
</syntaxhighlight>

==Json Patch Operations==
===Intro===
A JSON Patch document is just a JSON file containing an array of patch operations. The patch operations supported by JSON Patch are “add”, “remove”, “replace”, “move”, “copy” and “test”. The operations are applied in order: if any of them fail then the whole patch operation should abort.
===Add===
<syntaxhighlight lang="json">
{ "op": "add", "path": "/biscuits/1", "value": { "name": "Ginger Nut" } }
</syntaxhighlight>

Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.

===Remove===
<syntaxhighlight lang="json">
{ "op": "remove", "path": "/biscuits" }
</syntaxhighlight>
Removes a value from an object or array.

<syntaxhighlight lang="json">
{ "op": "remove", "path": "/biscuits/0" }
</syntaxhighlight>
Removes the first element of the array at biscuits (or just removes the “0” key if biscuits is an object)

===Replace===
<syntaxhighlight lang="json">
{ "op": "replace", "path": "/biscuits/0/name", "value": "Chocolate Digestive" }
</syntaxhighlight>
Replaces a value. Equivalent to a “remove” followed by an “add”.

===Copy===
<syntaxhighlight lang="json">
{ "op": "copy", "from": "/biscuits/0", "path": "/best_biscuit" }
</syntaxhighlight>
Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers.

===Move===
<syntaxhighlight lang="json">
{ "op": "move", "from": "/biscuits", "path": "/cookies" }
</syntaxhighlight>
Moves a value from one location to the other. Both from and path are JSON Pointers.

===Test===
<syntaxhighlight lang="json">
{ "op": "test", "path": "/best_biscuit/name", "value": "Choco Leibniz" }
</syntaxhighlight>
Tests that the specified value is set in the document. If the test fails, then the patch as a whole should not apply.

==Performing a Patch update==
===C# Code===
We need to add the library to support json patch to the project
<syntaxhighlight lang="bash">
dotnet add package Microsoft.AspNetCore.JsonPatch
</syntaxhighlight>
The code to apply a patch is similar to the code to apply an update
<syntaxhighlight lang="c#">
        [HttpPatch("{courseId}")]
        public ActionResult PartiallyUpdateCourseForAuthor(
            Guid authorId,
            Guid courseId,
            JsonPatchDocument<CourseForUpdateDto> patchDocument)
        {
            // Check Author Exists              
            if (_courseLibraryRepository.AuthorExists(authorId) == false) return NotFound();

            // Check Course Exists              
            var courseForAuthorFromRepo = _courseLibraryRepository.GetCourse(authorId, courseId);
            if (courseForAuthorFromRepo == null)
            {
                return NotFound();
            }

            var courseToPatch = _mapper.Map<CourseForUpdateDto>(courseForAuthorFromRepo);

            patchDocument.ApplyTo(courseToPatch, ModelState);

            if (!TryValidateModel(courseToPatch))
            {
                return ValidationProblem(ModelState);
            }

            _mapper.Map(courseToPatch, courseForAuthorFromRepo);

            _courseLibraryRepository.UpdateCourse(courseForAuthorFromRepo);
            _courseLibraryRepository.Save();
            return NoContent();
       }
</syntaxhighlight>

===Microsoft Json Parser===
This parser is not a proficient as the newton parser so we need to add that to the project
<syntaxhighlight lang="bash">
dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson
</syntaxhighlight>
We need to also add this to the startup code.
<syntaxhighlight lang="c#">
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers(setupAction =>
            {
                setupAction.ReturnHttpNotAcceptable = true;
            })
...
            .AddXmlDataContractSerializerFormatters()
            .AddNewtonsoftJson(setupAction => 
            {
                setupAction.SerializerSettings.ContractResolver = 
                     new CamelCasePropertyNamesContractResolver();
            })
...
            .ConfigureApiBehaviorOptions(
</syntaxhighlight>

Note the ordering of the statements determines which format the default is. So in the case we need to swap the statement around to have json first e.g.

<syntaxhighlight lang="c#">
            .AddNewtonsoftJson(setupAction => 
            {
                setupAction.SerializerSettings.ContractResolver = 
                     new CamelCasePropertyNamesContractResolver();
            })
            .AddXmlDataContractSerializerFormatters()

</syntaxhighlight>

===Validation===
We can override the validation to point back to the ApiBehaviourOptions we created above.
<syntaxhighlight lang="c#">
        public override ActionResult ValidationProblem(
            [ActionResultObjectValue] ModelStateDictionary modelStateDictionary)
        {
            var options = HttpContext.RequestServices.GetRequiredService<IOptions<ApiBehaviorOptions>>();
            return (ActionResult)options.Value.InvalidModelStateResponseFactory(ControllerContext);
        }
</syntaxhighlight>
===Upserting for Patch===
This is the same as upserting for Put. If it does not exist then create it.
<syntaxhighlight lang="c#">
            // Check Course Exists              
            var courseForAuthorFromRepo = _courseLibraryRepository.GetCourse(authorId, courseId);
            if (courseForAuthorFromRepo == null)
            {
                var courseDto = new  CourseForUpdateDto();

                patchDocument.ApplyTo(courseDto, ModelState);

                if (!TryValidateModel(courseDto))
                {
                    return ValidationProblem(ModelState);
                }

                var courseToAdd = _mapper.Map<Course>(courseDto);
                courseToAdd.Id = courseId;

                // As per HttpPut
                _courseLibraryRepository.AddCourse(authorId, courseToAdd);
                _courseLibraryRepository.Save();

                var courseToReturn = _mapper.Map<CourseDto>(courseToAdd);

                return CreatedAtRoute("GetCoursesForAuthor",
                    new { authorId = authorId, courseId = courseToReturn.Id },
                    courseToReturn);
            }
</syntaxhighlight>

=Deleting Resources=
This is very straight forward.
<syntaxhighlight lang="c#">
        [HttpDelete("{courseId}")]
        public IActionResult DeleteCourseForAuthor(Guid authorId, Guid courseId)
        {
            if (_courseLibraryRepository.AuthorExists(authorId) == false) return NotFound();

            var courseForAuthorFromRepo = _courseLibraryRepository.GetCourse(authorId, courseId);

            if (courseForAuthorFromRepo == null) return NotFound();

            _courseLibraryRepository.DeleteCourse(courseForAuthorFromRepo);
            _courseLibraryRepository.Save();

            return NoContent();
        }
</syntaxhighlight>

=RESTFul Advanced Topics=

==Paging==
===Deferred Execution===
Deferred queries are expression which are not evaluated until the query is used. This allows the user to continue to add constraints without taking a performance hit. e.g.
<syntaxhighlight lang="c#">
var collection = _context.Authors as IQueryable<Author>;
collection = collection.Where(x => x.MainCategory == myMainCategory);             }
</syntaxhighlight>
=== Paging through Collection Resources ===
* Parameters can be passed via query string e.g.
 http://host/api/authors?pageNumber=1&pageSize=5
* Page size should be limited
* Page by default
=== Implement Helper Class ForPaging ===
<syntaxhighlight lang="c#">
    public class PagedList<T> : List<T>
    {
        public int CurrentPage { get; private set; }
        public int TotalPages { get; private set; }
        public int PageSize { get; private set; }
        public int TotalCount { get; private set; }
        public bool HasPrevious => (CurrentPage > 1);
        public bool HasNext => (CurrentPage < TotalPages);

        public PagedList(List<T> items, int count, int pageNumber, int pageSize)
        {
            TotalCount = count;
            PageSize = pageSize;
            CurrentPage = pageNumber;
            TotalPages = (int)System.Math.Ceiling(count / (double)pageSize);
            AddRange(items);
        }

        // Factory
        public static PagedList<T> Create(IQueryable<T> source, int pageNumber, int pageSize)
        {
            var count = source.Count();
            var items = source.Skip((pageNumber -1) * pageSize).Take(pageSize).ToList();
            return new PagedList<T>(items,count,pageNumber,pageSize);
        }
    }

</syntaxhighlight>
=== Implementing Paging ===
This easy using the take and skip provided by IQueryTable. Add this to the Get method.
<syntaxhighlight lang="c#">
return collection
 .Skip(authorsResourceParameters.PageSize * (authorsResourceParameters.PageNumber - 1))
 .Take(authorsResourceParameters.PageSize)
 .ToList();
</syntaxhighlight>

=== Returning Pagination Data in ASP .Net ===
====Introduction====
To Do this we need to 
* Change repository to return PagedList
* Create enumerator for previous and next page
* Build Uri Based on previous or next page
* Change GET to implement pagination
** Create previous link
** Create next link
** Create Pagination data
** Add it to the headers
==== Change repository to return PagedList====
<syntaxhighlight lang="c#">
        public PagedList<Author> GetAuthors(AuthorsResourceParameters authorsResourceParameters)
        {
            if (string.IsNullOrEmpty(authorsResourceParameters.MainCategory) && string.IsNullOrEmpty(authorsResourceParameters.SearchQuery)) return _context.Authors.ToList<Author>();

....
            return PagedList<Author>.Create(collection,
                authorsResourceParameters.PageNumber,
                authorsResourceParameters.PageSize);

</syntaxhighlight>

==== Create Enum for Previous and Next Page ====
<syntaxhighlight lang="c#">
public enum ResourceUriType
{
    PreviousPage,
    NextPage,
    CurrentPage
}
</syntaxhighlight>

====Build Uri Based on previous or next page====
<syntaxhighlight lang="c#">
        private string CreateAuthorsResourceUri(
            AuthorsResourceParameters authorsResourceParameters,
            ResourceUriType resourceUriType)
        {
            switch (resourceUriType)
            {
                case ResourceUriType.PreviousPage:
                    return Url.Link("GetAuthors",
                        new
                        {
                            pageNumber = authorsResourceParameters.PageNumber - 1,
                            pageSize = authorsResourceParameters.PageSize,
                            mainCategory = authorsResourceParameters.MainCategory,
                            searchQuery = authorsResourceParameters.SearchQuery,
                            orderBy = authorsResourceParameters.OrderBy,
                            fields = authorsResourceParameters.Fields,
                        });

                case ResourceUriType.NextPage:
                    return Url.Link("GetAuthors",
                        new
                        {
                            pageNumber = authorsResourceParameters.PageNumber + 1,
                            pageSize = authorsResourceParameters.PageSize,
                            mainCategory = authorsResourceParameters.MainCategory,
                            searchQuery = authorsResourceParameters.SearchQuery,
                            orderBy = authorsResourceParameters.OrderBy,
                            fields = authorsResourceParameters.Fields,
                        });
                case ResourceUriType.CurrentPage:
                default:
                    return Url.Link("GetAuthors",
                        new
                        {
                            pageNumber = authorsResourceParameters.PageNumber,
                            pageSize = authorsResourceParameters.PageSize,
                            mainCategory = authorsResourceParameters.MainCategory,
                            searchQuery = authorsResourceParameters.SearchQuery,
                            orderBy = authorsResourceParameters.OrderBy,
                            fields = authorsResourceParameters.Fields,
                        });
            }
 
</syntaxhighlight>

====Change GET To Implement Pagination====
<syntaxhighlight lang="c#">
        [HttpGet(Name = "GetAuthors")]
        [HttpHead]
        public ActionResult<IEnumerable<AuthorDto>> GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
            var authorsFromRepo = _courseLibraryRepository.GetAuthors(authorsResourceParameters);

            var previousPageLink = authorsFromRepo.HasPrevious ? 
                CreateAuthorsResourceUri(
                    authorsResourceParameters,
                    ResourceUriType.PreviousPage) : null;

            var nextPageLink = authorsFromRepo.HasNext ? 
                CreateAuthorsResourceUri(
                    authorsResourceParameters,
                    ResourceUriType.NextPage) : null;

            var paginationMetaData = new 
            {
                totalCount = authorsFromRepo.TotalCount,
                pageSize = authorsFromRepo.PageSize,
                currentPage = authorsFromRepo.CurrentPage,
                totalPages = authorsFromRepo.TotalPages,
                previousPageLink,
                nextPageLink
            };

            Response.Headers.Add("X-Pagination",
                JsonSerializer.Serialize(paginationMetaData));

            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo));
        }
</syntaxhighlight>

==Sorting==
===Add Dynamic Linq===
<syntaxhighlight lang="c#">
dotnet add package System.Linq.Dynamic.Core
</syntaxhighlight>
===Property Mapping Service===
The course suggested a property mapping service which allows a DTO name to be mapped to 1-n number of fields on the entity. It also suggested it should encapulate whether the mapper needed to be reversed. E.g. Mapping Age to DateOfBirth means we would want them in reverse order. Here was an overview of design
 PropertyMappingService : IPropertyMappingService
   IList<IPropertyMapping> propertyMappings  e.g. AuthorDto to Author
      PropertyMapping<TSource, TDestination> : IPropertyMapping
          Dictionary<string, PropertyMappingValue>
              PropertyMappingValue
                  DestinationProperties      e.g. FirstName, LastName
                  Revert                     e.g. true for Age => DateOfBirth
 
   GetPropertyMapping<TSource, TDestination>() e.g. from AuthorDto to Author
===Property Mapping Service Implementation ===
====Property Mapping Value====
<syntaxhighlight lang="c#">
    public class PropertyMappingValue
    {
        public IEnumerable<string> DestinationProperties { get; private set; }
        public bool Revert { get; private set; }

        public PropertyMappingValue(
            IEnumerable<string> destinationProperties,
            bool revert = false)
        {
            DestinationProperties = destinationProperties
                ?? throw new ArgumentNullException(nameof(destinationProperties));
            Revert = revert;
        }
    }
</syntaxhighlight>

====Property Mapping====
Create an interface
<syntaxhighlight lang="c#">
    public interface IPropertyMapping
    {
    }
</syntaxhighlight>
And create an implementation of the interface
<syntaxhighlight lang="c#">
    public class PropertyMapping<TSource, TDestination> : IPropertyMapping
    {
        public Dictionary<string, PropertyMappingValue> _mappingDictionary {get; private set;}

        public PropertyMapping(Dictionary<string, PropertyMappingValue> mappingDictionary)
        {   
            _mappingDictionary = mappingDictionary ?? 
                throw new ArgumentNullException(nameof(mappingDictionary));
        }
    }
</syntaxhighlight>
====Property Mapping Service====
Create an interface
<syntaxhighlight lang="c#">
    public interface IPropertyMappingService
    {
        Dictionary<string, PropertyMappingValue> GetPropertyMapping<TSource, TDestination>();
    }
</syntaxhighlight>
And create an implementation of the interface
<syntaxhighlight lang="c#">
    public class PropertyMappingService : IPropertyMappingService
    {
        private Dictionary<string, PropertyMappingValue> _authorPropertyMapping =
            new Dictionary<string, PropertyMappingValue>(StringComparer.OrdinalIgnoreCase)
            {
                {"Id", new PropertyMappingValue(new List<string>() {"Id"}) },
                {"MainCategory", new PropertyMappingValue(new List<string>() {"MainCategory"}) },
                {"Age", new PropertyMappingValue(new List<string>() {"DateOfBirth"},true) },
                {"Name", new PropertyMappingValue(new List<string>() {"FirstName", "LastName"}) }
            };

        private IList<IPropertyMapping> _propertyMappings =  new List<IPropertyMapping>();            

        public PropertyMappingService()
        {
            _propertyMappings.Add(new PropertyMapping<AuthorDto,Author>(_authorPropertyMapping));
        }

        public Dictionary<string, PropertyMappingValue> GetPropertyMapping<TSource, TDestination>()
        {
            var matchingMapping = _propertyMappings.OfType<PropertyMapping<TSource,TDestination>>();

            if(matchingMapping.Count() == 1)
            {
                return matchingMapping.First()._mappingDictionary;
            }

            throw new Exception($"Cannot find exact property mapping instance " +
                $"for <{typeof(TSource)},{typeof(TDestination)}>");
        }
    }
</syntaxhighlight>

====Add Service to the Container====
Under Startup
<syntaxhighlight lang="c#">
            services.AddTransient<IPropertyMappingService, PropertyMappingService>();
</syntaxhighlight>

===Change Repository to use Mapping Service ===
Add it to the constructor of the repository and in the GetAuthors method add the OrderBy code as the last step.
<syntaxhighlight lang="c#">

        public PagedList<Author> GetAuthors(AuthorsResourceParameters authorsResourceParameters)
        {
...
            if (!string.IsNullOrWhiteSpace(authorsResourceParameters.OrderBy))
            {
               
                // Get property mapping dictionary
                var authorPropertyMappingDictionary = _propertyMappingService.GetPropertyMapping<AuthorDto,Author>();
                collection = collection.ApplySort(
                    authorsResourceParameters.OrderBy, 
                    authorPropertyMappingDictionary);
            }

</syntaxhighlight>

===Create Extension Method on IQueryable===
This does most of the work. It validates the arguments, extracts the properties and builds the orderby clause.
<syntaxhighlight lang="c#">
    public static class IQueryableExtensions
    {
        public static IQueryable<T> ApplySort<T>(
            this IQueryable<T> source,
            string orderBy,
            Dictionary<string, PropertyMappingValue> mappingDictionary)
        {
            var orderByString = "";

            // Validate input
            if (source == null) throw new ArgumentNullException(nameof(source));
            if (mappingDictionary == null) throw new ArgumentNullException(nameof(mappingDictionary));
            if (string.IsNullOrWhiteSpace(orderBy)) return source;

            // Split the orderby up
            var orderByAfterSplit = orderBy.Split(",");

            // Apply order by clause in reverse order otherwise the 
            // IQueryable will be ordered in wrong order
            foreach (var orderByClause in orderByAfterSplit.Reverse())
            {
                // Trim
                var trimmedOrderByClause = orderByClause.Trim();

                // Check for direction
                var orderByDescending = trimmedOrderByClause.EndsWith(" desc");

                // Get the property name
                //   Remove asc or desc 
                var indexOfFirstSpace = trimmedOrderByClause.IndexOf(" ");
                var propertyName = indexOfFirstSpace == -1 ?
                        trimmedOrderByClause :
                        trimmedOrderByClause.Remove(indexOfFirstSpace);

                // Check in the mapping dictionary
                if (!mappingDictionary.ContainsKey(propertyName))
                    throw new ArgumentException($"Key Mapping for Property Name {propertyName} is missing.");

                var propertyMappingValue = mappingDictionary[propertyName];

                // Check value is not null
                if (propertyMappingValue == null)
                    throw new Exception($"Property Mapping Value {propertyMappingValue} is null");

                // Iterate over the property names
                // so the orderby clauses are applied in the correct order
                foreach (var destinationProperty in propertyMappingValue.DestinationProperties)
                {
                    // Revert sort order if necessary
                    if (propertyMappingValue.Revert) orderByDescending = !orderByDescending;

                    orderByString = orderByString +
                        (string.IsNullOrWhiteSpace(orderByString) ?
                            string.Empty :
                            ", ") +
                            destinationProperty +
                            (orderByDescending ?
                            " descending" :
                            " ascending");
                }
            }

            return source.OrderBy(orderByString);
        }
    }
</syntaxhighlight>

===Validate the OrderBy===
We should check the orderby is a correct request to ensure the correct status code is returned. Lets 
* Create a function on the service 
* Implement on the controller
====Create a function on the service====
Add to interface and implement in the service
<syntaxhighlight lang="c#">
        public bool ValidMappingExistsFor<TSource, TDestination>(string fields)
        {
            var propertyMapping = GetPropertyMapping<TSource, TDestination>();

            if (string.IsNullOrWhiteSpace(fields)) return true;

            var splitFields = fields.Split(",");

            foreach (var splitField in splitFields)
            {
                var trimmedSplitField = splitField.Trim();

                // Remove everything after " " e.g. asc 
                var indexOfSpace = trimmedSplitField.IndexOf(" ");
                var propertyName = indexOfSpace == -1 ?
                    trimmedSplitField :
                    trimmedSplitField.Remove(indexOfSpace);

                // Find matching property 
                if (!propertyMapping.ContainsKey(propertyName)) return false;
            }
            return true;
        }
</syntaxhighlight>
====Implement on the Controller====
Checks the mapping and returns Bad Request on failure.
<syntaxhighlight lang="c#">
        [HttpGet(Name = "GetAuthors")]
        [HttpHead]
        public ActionResult<IEnumerable<AuthorDto>> GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
            if (!_propertyMappingService.ValidMappingExistsFor<AuthorDto, Author>(authorsResourceParameters.OrderBy))
            {
                return BadRequest();
            }
....
</syntaxhighlight>
==Shaping==
===Shaping===
Shaping is when you want a selection of the data and not the whole resource. E.g. For an author you only want the Id and Name but not the date of birth. To achieve this we can create a Helper function on IEnumerable using ExpandoObject 
===Implementation on Collection===
We create a helper class which takes the whole result as input and returns only the fields required as the result using reflection.
<syntaxhighlight lang="c#">
        public static IEnumerable<ExpandoObject> ShapeData<TSource>(
            this IEnumerable<TSource> source,
            string fields)
        {
            if (source == null) throw new ArgumentNullException(nameof(source));

            // Create ExpandoObject to store result
            var expandoObjectList = new List<ExpandoObject>();

            // Create a list of PropertyInfos for source. Reflection is expensive
            // so rather than doing it for each object, we do it once and resue
            var propertyListInfo = new List<PropertyInfo>();

            if (string.IsNullOrWhiteSpace(fields))
            {
                // all public properties should be in the expandoObject
                var propertyInfos = typeof(TSource).GetProperties(BindingFlags.PutDispProperty | BindingFlags.Instance);
                propertyListInfo.AddRange(propertyInfos);
            }
            else
            {
                var fieldsAfterSplit = fields.Split(",");

                foreach (var field in fieldsAfterSplit)
                {
                    // Trim
                    var propertyName = field.Trim();

                    // use reflection to get the property name and value
                    var propertyInfo = typeof(TSource).GetProperty(
                        propertyName,
                        // we need to include public and instance, b/c specifying a 
                        // binding flag overwrites the already-existing binding flags.
                        BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.Instance);

                    if (propertyInfo == null)
                        throw new Exception($"Property {propertyName} wasn't found on {typeof(TSource)}");

                    propertyListInfo.Add(propertyInfo);
                }
            }

            // Now lets create the ExpandoObject for each item in TSource
            foreach (TSource sourceObject in source)
            {
                // Create expandoObject
                var dataShapeObject = new ExpandoObject();

                // Get the value for each Property we have to return
                foreach (var propertyInfo in propertyListInfo)
                {
                    // Get the value of the property 
                    var propertyValue = propertyInfo.GetValue(sourceObject);

                    // Add the field to the ExpandoObject
                    ((IDictionary<string, object>)dataShapeObject).Add(propertyInfo.Name, propertyValue);
                }
                expandoObjectList.Add(dataShapeObject);
            }
            return expandoObjectList;
        }
</syntaxhighlight>
Don't forget to implement this on the controller by changing the GetAuthors to return an IActionResult and to call the ShapeData extension method.
<syntaxhighlight lang="c#">

        [HttpGet(Name = "GetAuthors")]
        [HttpHead]
        public IActionResult GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
...
            return Ok(_mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo).ShapeData(authorsResourceParameters.Fields));
        }

</syntaxhighlight>
===Implementation on Object===
====Helper to build the Shape Data====
This is required because reflection is very expensive. Suspect we could have a shared helper class to combine these.
<syntaxhighlight lang="c#">
        public static ExpandoObject ShapeData<TSource>(
            this TSource source,
            string fields)
        {
            if (source == null) throw new ArgumentNullException(nameof(source));

            var dataShapedObject = new ExpandoObject();

            if (string.IsNullOrWhiteSpace(fields))
            {
                // all public properties should be in the ExpandoObject 
                var propertyInfos = typeof(TSource)
                        .GetProperties(BindingFlags.IgnoreCase |
                        BindingFlags.Public | BindingFlags.Instance);

                foreach (var propertyInfo in propertyInfos)
                {
                    // get the value of the property on the source object
                    var propertyValue = propertyInfo.GetValue(source);

                    // add the field to the ExpandoObject
                    ((IDictionary<string, object>)dataShapedObject)
                        .Add(propertyInfo.Name, propertyValue);
                }

                return dataShapedObject;
            }

            // the field are separated by ",", so we split it.
            var fieldsAfterSplit = fields.Split(',');

            foreach (var field in fieldsAfterSplit)
            {
                // Trim
                var propertyName = field.Trim();

                // use reflection to get the property name and value
                var propertyInfo = typeof(TSource)
                    .GetProperty(propertyName,
                    // we need to include public and instance, b/c specifying a 
                    // binding flag overwrites the already-existing binding flags.
                    BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.Instance);

                // If not found error
                if (propertyInfo == null)
                    throw new Exception($"Property {propertyName} wasn't found on {typeof(TSource)}");

                // get the value of the property on the source object
                var propertyValue = propertyInfo.GetValue(source);

                // add the field to the ExpandoObject
                ((IDictionary<string, object>)dataShapedObject)
                    .Add(propertyInfo.Name, propertyValue);
            }

            // return the list
            return dataShapedObject;
        }
</syntaxhighlight>
====Service to Test the Property Names are Valid====
This can be put in a transient service and injected into the controller. I checks the type passed to ensure the field names requested exist in the class name requested.
<syntaxhighlight lang="c#">
        public bool TypeHasProperties<T>(string fields)
        {
            if (fields == null) return true;

            // Split fields
            var fieldsAfterSplit = fields.Split(",");

            foreach (var field in fieldsAfterSplit)
            {
                var propertyName = field.Trim();

                var propertyInfo = typeof(T)
                    .GetProperty(propertyName,
                    BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.Instance);

                if (propertyInfo == null) return false;

            }

            return true;
        }

</syntaxhighlight>
====Implement in the Controller====
Add the Service to the startup and controller. Call when requesting a AuthorDto. This ensures that the correct status is returned. Not checking will mean an exception is thrown which is a 500.
<syntaxhighlight lang="c#">
        [HttpGet(Name = "GetAuthors")]
        [HttpHead]
        public IActionResult GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
            if (!_propertyMappingService.ValidMappingExistsFor<AuthorDto, Author>(authorsResourceParameters.OrderBy))
            {
                return BadRequest();
            }

            if (!_propertyCheckerService.TypeHasProperties<AuthorDto>(authorsResourceParameters.Fields))
            {
                return BadRequest();
            }
</syntaxhighlight>
===Additional Options===
You could add the following to the API
'''Include Child Resources'''
* http://host/api/authors?expand=course
* http://host/api/authors?fields=courses.id
'''Advanced Filters'''
* http://host/api/authors?name.contains('Kevin')

==HATEOAS==
===Introduction===
HATEOAS (Hypermedia as the Engine of Application State)
* Helps the evolvability and self-descriptiveness
* Drives how to consume and use the API

'''You can't have evolvability if clients have their controls baked into their design at deployment. Controls have to be learned on the fly. That's what hypermedia enables. - Roy Fielding'''
===Supporting HATEOAS Example===
To support this for our Authors example we want to provide links to
* GET Author
* DELETE Author
* POST Course
* GET Courses
====Create Class to hold links====
Nothing to see here
<syntaxhighlight lang="c#">
    public class LinkDto
    {
        public string Href {get; private set;}
        public string Rel {get; private set;}
        public string Method {get; private set;}
        public LinkDto(string href, string rel, string method)
        {
            Href = href;
            Rel = rel;
            Method = method;
        }
    }
</syntaxhighlight>
====Add Generation of Links to Controller====
Make sure the methods are labelled appropriately and build the links into a list
<syntaxhighlight lang="c#">
        public IEnumerable<LinkDto> CreateLinkForAuthor(Guid authorId, string fields)
        {
            var links = new List<LinkDto>();

            if (string.IsNullOrWhiteSpace(fields))
            {
                links.Add(new LinkDto(
                    Url.Link("GetAuthor", new { authorId }),
                    "self",
                    "GET"));
            }
            else
            {
                links.Add(new LinkDto(
                    Url.Link("GetAuthor", new { authorId, fields }),
                    "self",
                    "GET"));
            }

            links.Add(new LinkDto(
                Url.Link("DeleteAuthor", new { authorId }),
                "delete_author",
                "DELETE"));

            links.Add(new LinkDto(
                Url.Link("CreateCourseForAuthor", new { authorId }),
                "create_course",
                "POST"));

           links.Add(new LinkDto(
                Url.Link("GetCoursesForAuthor", new { authorId }),
                "get_courses",
                "GET"));

            return links;
        }
</syntaxhighlight>

====Amend GetAuthor to Add Links====
ShapedData is a Dictionary of string, Object. Let's put the links into this for GetAuthors
<syntaxhighlight lang="c#">
        public IActionResult GetAuthor(Guid authorId, string fields)
        {
...
            var links = CreateLinkForAuthor(authorId, fields);

            var linkedResourcesToReturn =
                _mapper.Map<AuthorDto>(authorsFromRepo).ShapeData(fields) as
                IDictionary<string, object>;

            linkedResourcesToReturn.Add("links", links);

            return Ok(linkedResourcesToReturn);
        }
</syntaxhighlight>

====Result====
Here is an example of the code.
[[File:GetAuthor HATEOAS.png]]

===Supporting HATEOAS For Create===
Simple amend the CreateAuthors to use the already created code. 
<syntaxhighlight lang="c#">
        [HttpPost]
        public ActionResult<AuthorDto> CreateAuthor(AuthorForCreationDto author)
        {
...

            var links = CreateLinkForAuthor(authorToReturn.Id, null);

            var linkedResourcesToReturn =
                _mapper.Map<AuthorDto>(authorToReturn).ShapeData(null) as
                IDictionary<string, object>;

            linkedResourcesToReturn.Add("links", links);

            return CreatedAtRoute("GetAuthor",
                new { authorId = linkedResourcesToReturn["Id"] },
                linkedResourcesToReturn);
        }
</syntaxhighlight>

===Supporting HATEOAS For A Collection===

====Create Links for Authors====
We need to create links for authors
<syntaxhighlight lang="c#">
        public IEnumerable<LinkDto> CreateLinksForAuthors(
            AuthorsResourceParameters authorsResourceParameters)
        {
            var links = new List<LinkDto>();

            links.Add(
                new LinkDto(CreateAuthorsResourceUri(
                    authorsResourceParameters,
                    ResourceUriType.CurrentPage),
                "self",
                "GET"));

            return links;
        }
</syntaxhighlight>

====Change GetAuthors to use this====
Creating of the links for each author is the same as the GetAuthor. 
<syntaxhighlight lang="c#">
        [HttpGet(Name = "GetAuthors")]
        [HttpHead]
        public IActionResult GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
...
            Response.Headers.Add("X-Pagination",
                JsonSerializer.Serialize(paginationMetaData, options));

            // Create Links for Get Authors
            var links = CreateLinksForAuthors(authorsResourceParameters);

            // Get the authors shaped
            var shapedAuthors = _mapper.Map<IEnumerable<AuthorDto>>(authorsFromRepo)
                .ShapeData(authorsResourceParameters.Fields);

            // For each author add the links
            var shapedAuthorsWithLinks = shapedAuthors.Select(author =>
            {
                // Make easier to work with by converting to Dictionary as before
                var authorAsDictionary = author as IDictionary<string, object>;

                // Create Links
                var authorLinks = CreateLinkForAuthor((Guid)authorAsDictionary["Id"], null);

                // Add to Dictionary
                authorAsDictionary.Add("Links", authorLinks);

                return authorAsDictionary;
            });

            // Put the links and the shapedAuthors with Links in a object
            var linkedCollectionResource = new 
            {
                value = shapedAuthorsWithLinks,
                links
            };

            return Ok(linkedCollectionResource);
        }
</syntaxhighlight>

===Supporting HATEOAS for Pagination Links===
We should remove the pagination links in custom header and replace them with HATEOAS links. To do this we will
* Change CreateLinksForAuthors to add links for next and previous

====Change CreateLinksForAuthors====
<syntaxhighlight lang="c#">
        public IEnumerable<LinkDto> CreateLinksForAuthors(
            AuthorsResourceParameters authorsResourceParameters,
            bool HasNext,
            bool HasPrevious)
        {
...
            if(HasNext)
            {
                links.Add(
                    new LinkDto(CreateAuthorsResourceUri(
                        authorsResourceParameters,
                        ResourceUriType.NextPage),
                    "nextPage",
                    "GET"));
            }

            if(HasPrevious)
            {
                links.Add(
                    new LinkDto(CreateAuthorsResourceUri(
                        authorsResourceParameters,
                        ResourceUriType.PreviousPage),
                    "previousPage",
                    "GET"));
            }
       }
</syntaxhighlight>

====Change GetAuthors====
Remove previousPageLink and nextPageLink from metadata and add the values to the CreateLinksForAuthors.
<syntaxhighlight lang="c#">
        [HttpGet(Name = "GetAuthors")]
        [HttpHead]
        public IActionResult GetAuthors([FromQuery] AuthorsResourceParameters authorsResourceParameters)
        {
...
            var paginationMetaData = new
            {
                totalCount = authorsFromRepo.TotalCount,
                pageSize = authorsFromRepo.PageSize,
                currentPage = authorsFromRepo.CurrentPage,
                totalPages = authorsFromRepo.TotalPages,
            };

            var options = new System.Text.Json.JsonSerializerOptions()
            {
                Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
            };

            Response.Headers.Add("X-Pagination",
                JsonSerializer.Serialize(paginationMetaData, options));

            // Create Links for Get Authors
            var links = CreateLinksForAuthors(
                    authorsResourceParameters,
                    authorsFromRepo.HasNext,
                    authorsFromRepo.HasPrevious);
...
</syntaxhighlight>

===Adding a Root Document===
Just add all links from the root the user can access
<syntaxhighlight lang="c#">
   public class RootController : ControllerBase
    {
        [HttpGet(Name = "GetRoot")]
        public IActionResult GetRoot()
        {
            // Create links for root
            var links = new List<LinkDto>();

            links.Add(
                new LinkDto(
                    Url.Link("GetRoot", new { }),
                    "self",
                    "GET"));

            links.Add(
                new LinkDto(
                    Url.Link("GetAuthors", new { }),
                    "authors",
                    "GET"));

            links.Add(
                new LinkDto(
                    Url.Link("CreateAuthor", new { }),
                    "create_author",
                    "POST"));

            return Ok(links);
        }
    }
</syntaxhighlight>
===Other Approaches and Opetions===
* HAL (Hypertext Application Language)
** https://bit.ly/2YAyrUc
** Provides a set of conventions for expressing hyperlinks in either Json or XML
* Siren (Structured Interface for Representing Entities)
** https://github.com/kevinswiber/siren
** Link format and descriptions of what to send to those links
* Json-LD
** http://json-ld.org/
** Lightweight linked data format 
* Json-API
** https://jsonapi.org/
** Specification for building JSON APIs
* OData
** http://www.odata.org/
** Effort to standardize REST APIs
==Content Negotiation==
===Introduction===
In the examples above we added links to the output. But this is probably not desired for every call. We should create a media type and only return this information when the correct media type is requested.
===Vendor Specific Media Types===
Below is an example of how to name a vendor specific media type.
[[File:Mediatype restful.png]]
===Implementation===
This is simple enough. 
* Change Startup to
** Remove the original Output formatter
** Accept new media type
* Change the controller to
** Validate the media type
** Return the appropriate data

====Remove the original Output formatter====
<syntaxhighlight lang="c#">
            services.AddControllers(setupAction =>
            {
                setupAction.ReturnHttpNotAcceptable = true;
            })
</syntaxhighlight>
====Accept new media type====
<syntaxhighlight lang="c#">
            services.Configure<MvcOptions>(config =>
            {
                var newtownSoftJsonOutputFormatter = config.OutputFormatters
                    .OfType<Microsoft.AspNetCore.Mvc.Formatters.NewtonsoftJsonOutputFormatter>()?.FirstOrDefault();

                if (newtownSoftJsonOutputFormatter != null)
                {
                    newtownSoftJsonOutputFormatter.SupportedMediaTypes.Add("application/vnd.marvin.hateoas+json");
                }
            });
</syntaxhighlight>
====Validate the media type====
<syntaxhighlight lang="c#">
        [HttpGet("{authorId}", Name = "GetAuthor")]
        public IActionResult GetAuthor(Guid authorId, string fields,
        [FromHeader(Name ="Accept")] string mediaType)
        {
            if(!MediaTypeHeaderValue.TryParse(mediaType, out MediaTypeHeaderValue parsedMediaType))
            {
                return BadRequest();
            }
...
</syntaxhighlight>
====Return the appropriate data====
<syntaxhighlight lang="c#">
            if (parsedMediaType.MediaType == "application/vnd.marvin.hateoas+json")
            {
                var links = CreateLinkForAuthor(authorId, fields);

                var linkedResourcesToReturn =
                    _mapper.Map<AuthorDto>(authorsFromRepo).ShapeData(fields) as
                    IDictionary<string, object>;

                linkedResourcesToReturn.Add("links", links);

                return Ok(linkedResourcesToReturn);
            }

            return Ok(_mapper.Map<AuthorDto>(authorsFromRepo).ShapeData(fields));
        }
</syntaxhighlight>

===Making specific formats===
We can build different types of content depending on the request.
====Make a DTO to hold request====
Create a model to hold the DTO and add a profile to automapper
<syntaxhighlight lang="c#">
    public class AuthorFullDto
    {
        public Guid Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public DateTimeOffset DateOfBirth { get; set; }
        public string MainCategory { get; set; }
    }

    public class AuthorsProfile : Profile
    {
        public AuthorsProfile()
        {
...
            CreateMap<API.Entities.Author,Models.AuthorFullDto>();
</syntaxhighlight>
====Change Controller====
Apply the Produce attribute to the GetAuthor Action
<syntaxhighlight lang="c#">
        [Produces("application/json",
            "application/vnd.marvin.hateoas+json",
            "application/vnd.marvin.author.full+json",
            "application/vnd.marvin.author.full.hateoas+json",
            "application/vnd.marvin.author.friendly+json",
            "application/vnd.marvin.author.friendly.hateoas+json")]
        [HttpGet("{authorId}", Name = "GetAuthor")]
        public IActionResult GetAuthor(Guid authorId, string fields,
        [FromHeader(Name = "Accept")] string mediaType)
        {
</syntaxhighlight>
Change the contoller to put either the full or the friendly DTO out and add links where necessary.
<syntaxhighlight lang="c#">
            // Create List to hold links
            IEnumerable<LinkDto> links = new List<LinkDto>();

            // Add links if required
            if(includeLinks) links = CreateLinkForAuthor(authorId, fields);

            // Check for full author of the media type
            var primaryMediaType = includeLinks ? 
                parsedMediaType.SubTypeWithoutSuffix.Substring(
                        0,
                        parsedMediaType.SubTypeWithoutSuffix.Length - 8) :
                parsedMediaType.SubTypeWithoutSuffix;

            // If full media type
            if(primaryMediaType == "vnd.marvin.author.full")
            {
                var fullResourceToReturn = _mapper.Map<AuthorFullDto>(authorsFromRepo)
                    .ShapeData(fields) as IDictionary<string,object>;

                if(includeLinks) fullResourceToReturn.Add("links", links);

                return Ok(fullResourceToReturn);
            }

            // Else freindly type
            var friendlyResourceToReturn = _mapper.Map<AuthorDto>(authorsFromRepo)
                    .ShapeData(fields) as IDictionary<string,object>;

            if(includeLinks) friendlyResourceToReturn.Add("links", links);

            return Ok(friendlyResourceToReturn);
        }
</syntaxhighlight>

===Adding an Input Content Type===
The example provided was to add a date of death to the author. There are many ways to approach this but this approach is a concept not the way.

* Change the Author Entity to have DOD
* Change how we calculate Current Age
* Create a DTO with a Date of Death
* Change authors profile to add Date of death to GetCurrentAge and add map
* Create a Request Header Media Type Attribute
* In the controller copy CreateAuthor to CreateAuthorWithDateOfDeath and rename
* Add RequestHeaderMatchesMediaType and Consumes constraint to CreateAuthors and CreateAuthorsWithDateOfDeath

<pre style="color: red">RequestHeaderMatchedMediaType must be in reverse order. i.e. the default needs to be last</pre>

====Change the Author Entity to have DOD====
<syntaxhighlight lang="c#">
{
    public class Author
    {
...

        public DateTimeOffset? DateOfDeath { get; set; }          
</syntaxhighlight>

====Change how we calculate Current Age====
<syntaxhighlight lang="c#">
        public static int GetCurrentAge(
            this DateTimeOffset dataTimeOffset, 
            DateTimeOffset? dateOfDeath)
        {
            var currentDate = System.DateTime.UtcNow;

            if(dateOfDeath != null)
            {
                currentDate = dateOfDeath.Value.UtcDateTime;
            }

            var age = currentDate.Year - dataTimeOffset.Year;

            if (currentDate < dataTimeOffset.AddYears(age))
            {
                age--;
            }
            return age;
        }
</syntaxhighlight>
====Create a DTO with a Date of Death====
<syntaxhighlight lang="c#">
    public class AuthorForCreationWithDateOfDeathDto : AuthorForCreationDto
    {
        DateTimeOffset? DateOfDeath {get; set;}
    }
</syntaxhighlight>

====Change authors profile to add Date of death to GetCurrentAge and add map====
<syntaxhighlight lang="c#">
    public class AuthorsProfile : Profile
    {
        public AuthorsProfile()
        {
            CreateMap<API.Entities.Author, Models.AuthorDto>()
                .ForMember(
                   dest => dest.Name,
                   opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
                .ForMember(
                   dest => dest.Age,
                   opt => opt.MapFrom(src => src.DateOfBirth.GetCurrentAge(src.DateOfDeath)));

            CreateMap<Models.AuthorForCreationDto, API.Entities.Author>();

            CreateMap<Models.AuthorForCreationWithDateOfDeathDto, API.Entities.Author>();
...
</syntaxhighlight>
====Create a Request Header Media Type Attribute====
<syntaxhighlight lang="c#">
    [AttributeUsage(AttributeTargets.All, Inherited = true, AllowMultiple = true) ]
    public class RequestHeaderMatchedMediaTypeAttribute : Attribute, IActionConstraint
    {
        private readonly MediaTypeCollection _mediaTypes = new MediaTypeCollection();
        private readonly string _requestHeaderToMatch;

        public RequestHeaderMatchedMediaTypeAttribute(
            string requestHeaderToMatch,
            string mediaType, 
            params string[] otherMediaTypes)
        {
            _requestHeaderToMatch = requestHeaderToMatch ?? 
                throw new ArgumentNullException(requestHeaderToMatch);

            // Validate media type passed
            if(MediaTypeHeaderValue.TryParse(mediaType, out MediaTypeHeaderValue parsedMediaTypes))
            {
                _mediaTypes.Add(parsedMediaTypes);
            }
            else
            {
                throw new ArgumentException(nameof(mediaType));
            }

            foreach(var otherMediaType in otherMediaTypes)
            {
                if(MediaTypeHeaderValue.TryParse(otherMediaType, out MediaTypeHeaderValue parsedOtherMediaTypeMediaTypes))
                {
                    _mediaTypes.Add(parsedOtherMediaTypeMediaTypes);
                }
                else
                {
                    throw new ArgumentException(nameof(otherMediaTypes));
                }
            }
        }

        // Set to default
        public int Order => 0;

        public bool Accept(ActionConstraintContext context)
        {
            var requestHeaders = context.RouteContext.HttpContext.Request.Headers;
            
            // If not found do not accept
            if(!requestHeaders.ContainsKey(_requestHeaderToMatch)) return false;

            // Create Media type to compare to from the request header
            var parsedRequestMediaType = new MediaType(requestHeaders[_requestHeaderToMatch]);

            // If the media type is found the return true
            foreach(var mediaType in _mediaTypes)
            {
                var parsedMediaType = new MediaType(mediaType);

                // If found all good
                if(parsedRequestMediaType.Equals(parsedMediaType)) return true;
            }
            return false;
        }
    }
</syntaxhighlight>
====In the controller copy CreateAuthor to CreateAuthorWithDateOfDeath and rename====
<syntaxhighlight lang="c#">
        [HttpPost(Name = "CreateAuthorWithDateOfDeath")]
        public ActionResult<AuthorDto> CreateAuthorWithDateOfDeath(AuthorForCreationWithDateOfDeathDto author)
        {
            var authorEntity = _mapper.Map<Author>(author);
            _courseLibraryRepository.AddAuthor(authorEntity);
            _courseLibraryRepository.Save();

            var authorToReturn = _mapper.Map<AuthorDto>(authorEntity);

            var links = CreateLinkForAuthor(authorToReturn.Id, null);

            var linkedResourcesToReturn =
                _mapper.Map<AuthorDto>(authorToReturn).ShapeData(null) as
                IDictionary<string, object>;

            linkedResourcesToReturn.Add("links", links);

            return CreatedAtRoute("GetAuthor",
                new { authorId = linkedResourcesToReturn["Id"] },
                linkedResourcesToReturn);
        }

</syntaxhighlight>
=====Add RequestHeaderMatchesMediaType and Consumes constraint to CreateAuthors and CreateAuthorsWithDateOfDeath=====
<syntaxhighlight lang="c#">
...
        [HttpPost(Name = "CreateAuthorWithDateOfDeath")]
        [RequestHeaderMatchedMediaType("Content-Type", "application/vnd.marvin.authorforcreationwithdateofdeath+json")]
        [Consumes("application/vnd.marvin.authorforcreationwithdateofdeath+json")]
        public ActionResult<AuthorDto> CreateAuthorWithDateOfDeath(AuthorForCreationWithDateOfDeathDto author)
        {
...
        [HttpPost(Name = "CreateAuthor")]
        [RequestHeaderMatchedMediaType("Content-Type", "application/json","application/vnd.marvin.authorforcreation+json")]
        [Consumes("application/json", "application/vnd.marvin.authorforcreation+json")]
        public ActionResult<AuthorDto> CreateAuthor(AuthorForCreationDto author)
        {
...
</syntaxhighlight>
==Versioning in a RESTFul World==
The answer from the author is Don't but here are popular approaches
* Version the media types
** application/vnd.marvice.author.friendly.v1+json
** application/vnd.marvice.author.friendly.v2+json
* Through the URI api/v1/authors
* Through query string parameters api/v1/authors?api-version=v1
* Through a custom header "api-version"=v1