5. Introducing Hypermedia

using System.Text.Json.Serialization;

namespace Autobarn.Website.Api.Resources;

///<summary>A hypermedia link to a related resource.</summary>
public record Hyperlink(string Href);

///<summary>A set of hypermedia links, keyed by link relation, e.g. "self" or "next".</summary>
public class LinkList : Dictionary<string, Hyperlink>;

public abstract record Resource(
	[property: JsonPropertyName("_links"), JsonPropertyOrder(-1)]
	LinkList Links);

public record ApiRootResource(LinkList Links) : Resource(Links);

public record VehicleMakeResource(LinkList Links, string Code, string Name) : Resource(Links);

public record VehicleModelResource(LinkList Links, string Code, string Name) : Resource(Links);

public record VehicleResource(LinkList Links, string Registration, int Year, string Color) : Resource(Links);

public record ResourceList<T>(LinkList Links, int Index, int Count, int Total, IReadOnlyList<T> Items) : Resource(Links);

/// <summary>Names of the Autobarn API endpoints, used to generate hypermedia links.</summary>
public static class Endpoints {
	public const string GET_API_ROOT = nameof(GET_API_ROOT);
	public const string GET_VEHICLES = nameof(GET_VEHICLES);
	public const string GET_VEHICLE = nameof(GET_VEHICLE);
	public const string GET_MAKES = nameof(GET_MAKES);
	public const string GET_MAKE = nameof(GET_MAKE);
	public const string GET_MODELS_BY_MAKE = nameof(GET_MODELS_BY_MAKE);
	public const string GET_MODEL = nameof(GET_MODEL);
	public const string GET_VEHICLES_BY_MODEL = nameof(GET_VEHICLES_BY_MODEL);
}

public static class HypermediaExtensions {

	/// <summary>Creates a link to a named API endpoint, honouring the request's PathBase.</summary>
	public static Hyperlink LinkTo(this LinkGenerator links, HttpContext http, string endpointName, object? values = null)
		=> new(links.GetPathByName(http, endpointName, values)
			?? throw new InvalidOperationException($"Could not create a link to endpoint '{endpointName}'"));

	public static VehicleMakeResource ToResource(this VehicleMake make, LinkGenerator links, HttpContext http)
		=> new(
			Links: new() {
				["self"] = links.LinkTo(http, Endpoints.GET_MAKE, new { make = make.Code }),
				["models"] = links.LinkTo(http, Endpoints.GET_MODELS_BY_MAKE, new { make = make.Code })
			},
			Code: make.Code,
			Name: make.Name
		);

	public static VehicleModelResource ToResource(this VehicleModel model, LinkGenerator links, HttpContext http)
		=> new(
			Links: new() {
				["self"] = links.LinkTo(http, Endpoints.GET_MODEL, new { make = model.MakeCode, model = model.ModelCode }),
				["make"] = links.LinkTo(http, Endpoints.GET_MAKE, new { make = model.MakeCode }),
				["vehicles"] = links.LinkTo(http, Endpoints.GET_VEHICLES_BY_MODEL, new { make = model.MakeCode, model = model.ModelCode })
			},
			Code: model.Code,
			Name: model.Name
		);

	public static VehicleResource ToResource(this Vehicle vehicle, LinkGenerator links, HttpContext http)
		=> new(
			Links: new() {
				["self"] = links.LinkTo(http, Endpoints.GET_VEHICLE, new { registration = vehicle.Registration }),
				["model"] = links.LinkTo(http, Endpoints.GET_MODEL, new { make = vehicle.Model.MakeCode, model = vehicle.Model.ModelCode }),
				["make"] = links.LinkTo(http, Endpoints.GET_MAKE, new { make = vehicle.Model.MakeCode })
			},
			Registration: vehicle.Registration,
			Year: vehicle.Year,
			Color: vehicle.Color
		);
}

private const int DEFAULT_COUNT = 10;
private const int MAX_COUNT = 100;

private static LinkList Paginate(LinkGenerator links, HttpContext http, string endpointName, object? routeValues,
	int index, int count, int total) {
	ArgumentOutOfRangeException.ThrowIfNegative(index);
	ArgumentOutOfRangeException.ThrowIfNegativeOrZero(count);
	var result = new LinkList {
		["self"] = Page(index),
		["first"] = Page(0),
		["last"] = Page(Math.Max(0, (total - 1) / count * count))
	};
	if (index + count < total) result["next"] = Page(index + count);
	if (index > 0) result["prev"] = Page(Math.Max(0, index - count));
	return result;

	Hyperlink Page(int pageIndex) => links.LinkTo(http, endpointName,
		new RouteValueDictionary(routeValues) { ["index"] = pageIndex, ["count"] = count });
}

api.MapGet("/",
	(LinkGenerator links, HttpContext http) => TypedResults.Ok(new ApiRootResource(new() {
		["self"] = links.LinkTo(http, Endpoints.GET_API_ROOT),
		["vehicles"] = links.LinkTo(http, Endpoints.GET_VEHICLES),
		["makes"] = links.LinkTo(http, Endpoints.GET_MAKES)
	})))
	.WithName(Endpoints.GET_API_ROOT)
	.WithSummary("Autobarn API Discovery Endpoint")
	.WithDescription("Returns a list of links to the other endpoints in the Autobarn API.");

api.MapGet("/makes",
	async (AutobarnDbContext db) => await db.Makes.ToListAsync())
	.WithName("GetMakes")
	// ...

api.MapGet("/makes",
	async Task<Ok<ResourceList<VehicleMakeResource>>> (AutobarnDbContext db, LinkGenerator links, HttpContext http,
		[Range(0, int.MaxValue)] int index = 0,
		[Range(1, MAX_COUNT)] int count = DEFAULT_COUNT) => {
		var total = await db.Makes.CountAsync(http.RequestAborted);
		var makes = await db.Makes.AsNoTracking()
			.OrderBy(m => m.Code)
			.Skip(index).Take(count)
			.ToListAsync(http.RequestAborted);
		var items = makes.Select(m => m.ToResource(links, http)).ToList();
		var pageLinks = Paginate(links, http, Endpoints.GET_MAKES, null, index, count, total);
		return TypedResults.Ok(new ResourceList<VehicleMakeResource>(pageLinks, index, count, total, items));
	})
	.WithName(Endpoints.GET_MAKES)
	.WithSummary("List vehicle makes")
	.WithDescription("Returns a page of the manufacturers whose vehicles appear in the Autobarn catalogue.")
	.ProducesValidationProblem();

api.MapGet("/makes/{make}/models/{model}",
	async Task<Results<Ok<VehicleModelResource>, NotFound>> (AutobarnDbContext db, LinkGenerator links, HttpContext http, string make, string model)
		=> await db.Models.AsNoTracking()
			.FirstOrDefaultAsync(m => m.MakeCode == make && m.Code == $"{make}-{model}", http.RequestAborted) is { } result
			? TypedResults.Ok(result.ToResource(links, http))
			: TypedResults.NotFound())
	.WithName(Endpoints.GET_MODEL)
	.WithSummary("Find a vehicle model")
	.WithDescription("Returns the model with the given code built by the manufacturer with the given code, or 404 if no such model exists.");

api.MapGet("/makes/{make}/models/{model}/vehicles",
	async Task<Results<Ok<ResourceList<VehicleResource>>, NotFound>> (AutobarnDbContext db, LinkGenerator links, HttpContext http,
		string make, string model,
		[Range(0, int.MaxValue)] int index = 0,
		[Range(1, MAX_COUNT)] int count = DEFAULT_COUNT) => {
		var modelCode = $"{make}-{model}";
		if (!await db.Models.AnyAsync(m => m.MakeCode == make && m.Code == modelCode, http.RequestAborted)) return TypedResults.NotFound();
		var query = db.Vehicles.AsNoTracking().Where(v => v.ModelCode == modelCode);
		var total = await query.CountAsync(http.RequestAborted);
		var vehicles = await query
			.Include(v => v.Model)
			.OrderBy(v => v.Registration)
			.Skip(index).Take(count)
			.ToListAsync(http.RequestAborted);
		var items = vehicles.Select(v => v.ToResource(links, http)).ToList();
		var pageLinks = Paginate(links, http, Endpoints.GET_VEHICLES_BY_MODEL, new { make, model }, index, count, total);
		return TypedResults.Ok(new ResourceList<VehicleResource>(pageLinks, index, count, total, items));
	})
	// ...