API: Documenting the episode's api

AUTHORS.md

@@ -1,4 +1,4 @@
 # Authors
-Alphabetical order by first name.
+Ordered by the date of the first commit.
 
 * Zoe Roux ([@AnonymusRaccoon](http://github.com/AnonymusRaccoon))

CONTRIBUTING.md

@@ -25,6 +25,7 @@ Here are a few things you can do that will increase the likelihood of your pull
 
 ## Resources
 
+- [Why should you indent with tabs](https://www.reddit.com/r/javascript/comments/c8drjo/nobody_talks_about_the_real_reason_to_use_tabs/)
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
 - [Using Pull Requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
 - [GitHub Help](https://docs.github.com/en)

src/Kyoo.Abstractions/Models/Resources/Track.cs

@@ -73,7 +73,7 @@ namespace Kyoo.Abstractions.Models
 			{
 				string type = Type.ToString().ToLower();
 				string index = TrackIndex != 0 ? $"-{TrackIndex}" : string.Empty;
-				string episode = EpisodeSlug ?? Episode?.Slug ?? EpisodeID.ToString();
+				string episode = _episodeSlug ?? Episode?.Slug ?? EpisodeID.ToString();
 				return $"{episode}.{Language ?? "und"}{index}{(IsForced ? ".forced" : string.Empty)}.{type}";
 			}
 
@@ -90,7 +90,7 @@ namespace Kyoo.Abstractions.Models
 					                            "Format: {episodeSlug}.{language}[-{index}][.forced].{type}[.{extension}]");
 				}
 
-				EpisodeSlug = match.Groups["ep"].Value;
+				_episodeSlug = match.Groups["ep"].Value;
 				Language = match.Groups["lang"].Value;
 				if (Language == "und")
 					Language = null;
@@ -100,11 +100,6 @@ namespace Kyoo.Abstractions.Models
 			}
 		}
 
-		/// <summary>
-		/// The slug of the episode that contain this track. If this is not set, this track is ill-formed.
-		/// </summary>
-		[SerializeIgnore] public string EpisodeSlug { private get; set; }
-
 		/// <summary>
 		/// The title of the stream.
 		/// </summary>
@@ -153,7 +148,16 @@ namespace Kyoo.Abstractions.Models
 		/// <summary>
 		/// The episode that uses this track.
 		/// </summary>
-		[LoadableRelation(nameof(EpisodeID))] public Episode Episode { get; set; }
+		[LoadableRelation(nameof(EpisodeID))] public Episode Episode
+		{
+			get => _episode;
+			set
+			{
+				_episode = value;
+				if (_episode != null)
+					_episodeSlug = _episode.Slug;
+			}
+		}
 
 		/// <summary>
 		/// The index of this track on the episode.
@@ -184,6 +188,17 @@ namespace Kyoo.Abstractions.Models
 			}
 		}
 
+		/// <summary>
+		/// The slug of the episode that contain this track. If this is not set, this track is ill-formed.
+		/// </summary>
+		[SerializeIgnore] private string _episodeSlug;
+
+		/// <summary>
+		/// The episode that uses this track.
+		/// This is the baking field of <see cref="Episode"/>.
+		/// </summary>
+		[SerializeIgnore] private Episode _episode;
+
 		// Converting mkv track language to c# system language tag.
 		private static string _GetLanguage(string mkvLanguage)
 		{

src/Kyoo.Abstractions/Models/Utils/Constants.cs

@@ -34,6 +34,6 @@ namespace Kyoo.Abstractions.Models.Utils
 		/// <summary>
 		/// A group name for <see cref="ApiDefinitionAttribute"/>. It should be used for every <see cref="IResource"/>.
 		/// </summary>
-		public const string ResourceGroup = "Resources";
+		public const string ResourcesGroup = "Resources";
 	}
 }

src/Kyoo.Core/Controllers/Repositories/EpisodeRepository.cs

@@ -169,7 +169,6 @@ namespace Kyoo.Core.Controllers
 			resource.Tracks = await resource.Tracks.SelectAsync(x =>
 			{
 				x.Episode = resource;
-				x.EpisodeSlug = resource.Slug;
 				return _tracks.Create(x);
 			}).ToListAsync();
 			_database.Tracks.AttachRange(resource.Tracks);

src/Kyoo.Core/Views/CollectionApi.cs

@@ -40,7 +40,7 @@ namespace Kyoo.Core.Api
 	[Route("api/collection", Order = AlternativeRoute)]
 	[ApiController]
 	[PartialPermission(nameof(CollectionApi))]
-	[ApiDefinition("Collections", Group = ResourceGroup)]
+	[ApiDefinition("Collections", Group = ResourcesGroup)]
 	public class CollectionApi : CrudThumbsApi<Collection>
 	{
 		/// <summary>

src/Kyoo.Core/Views/EpisodeApi.cs

@@ -22,216 +22,145 @@ using System.Linq;
 using System.Threading.Tasks;
 using Kyoo.Abstractions.Controllers;
 using Kyoo.Abstractions.Models;
-using Kyoo.Abstractions.Models.Exceptions;
+using Kyoo.Abstractions.Models.Attributes;
 using Kyoo.Abstractions.Models.Permissions;
+using Kyoo.Abstractions.Models.Utils;
 using Kyoo.Core.Models.Options;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Options;
+using static Kyoo.Abstractions.Models.Utils.Constants;
 
 namespace Kyoo.Core.Api
 {
-	[Route("api/episode")]
+	/// <summary>
+	/// Information about one or multiple <see cref="Episode"/>.
+	/// </summary>
 	[Route("api/episodes")]
+	[Route("api/episode", Order = AlternativeRoute)]
 	[ApiController]
 	[PartialPermission(nameof(EpisodeApi))]
-	public class EpisodeApi : CrudApi<Episode>
+	[ApiDefinition("Episodes", Group = ResourcesGroup)]
+	public class EpisodeApi : CrudThumbsApi<Episode>
 	{
+		/// <summary>
+		/// The library manager used to modify or retrieve information in the data store.
+		/// </summary>
 		private readonly ILibraryManager _libraryManager;
-		private readonly IThumbnailsManager _thumbnails;
-		private readonly IFileSystem _files;
 
+		/// <summary>
+		/// Create a new <see cref="EpisodeApi"/>.
+		/// </summary>
+		/// <param name="libraryManager">
+		/// The library manager used to modify or retrieve information in the data store.
+		/// </param>
+		/// <param name="files">The file manager used to send images.</param>
+		/// <param name="thumbnails">The thumbnail manager used to retrieve images paths.</param>
+		/// <param name="options">
+		/// Options used to retrieve the base URL of Kyoo.
+		/// </param>
 		public EpisodeApi(ILibraryManager libraryManager,
-			IOptions<BasicOptions> options,
 			IFileSystem files,
-			IThumbnailsManager thumbnails)
+			IThumbnailsManager thumbnails,
-			: base(libraryManager.EpisodeRepository, options.Value.PublicUrl)
+			IOptions<BasicOptions> options)
+			: base(libraryManager.EpisodeRepository, files, thumbnails, options.Value.PublicUrl)
 		{
 			_libraryManager = libraryManager;
-			_files = files;
-			_thumbnails = thumbnails;
 		}
 
-		[HttpGet("{episodeID:int}/show")]
+		/// <summary>
+		/// Get episode's show
+		/// </summary>
+		/// <remarks>
+		/// Get the show that this episode is part of.
+		/// </remarks>
+		/// <param name="identifier">The ID or slug of the <see cref="Episode"/>.</param>
+		/// <returns>The show that contains this episode.</returns>
+		/// <response code="404">No episode with the given ID or slug could be found.</response>
+		[HttpGet("{identifier:id}/show")]
 		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Show>> GetShow(int episodeID)
+		[ProducesResponseType(StatusCodes.Status200OK)]
+		[ProducesResponseType(StatusCodes.Status404NotFound)]
+		public async Task<ActionResult<Show>> GetShow(Identifier identifier)
 		{
-			Show ret = await _libraryManager.GetOrDefault<Show>(x => x.Episodes.Any(y => y.ID == episodeID));
+			Show ret = await _libraryManager.GetOrDefault(identifier.IsContainedIn<Show, Episode>(x => x.Episodes));
 			if (ret == null)
 				return NotFound();
 			return ret;
 		}
 
-		[HttpGet("{showSlug}-s{seasonNumber:int}e{episodeNumber:int}/show")]
+		/// <summary>
+		/// Get episode's season
+		/// </summary>
+		/// <remarks>
+		/// Get the season that this episode is part of.
+		/// </remarks>
+		/// <param name="identifier">The ID or slug of the <see cref="Episode"/>.</param>
+		/// <returns>The season that contains this episode.</returns>
+		/// <response code="204">The episode is not part of a season.</response>
+		/// <response code="404">No episode with the given ID or slug could be found.</response>
+		[HttpGet("{identifier:id}/season")]
 		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Show>> GetShow(string showSlug, int seasonNumber, int episodeNumber)
+		[ProducesResponseType(StatusCodes.Status200OK)]
+		[ProducesResponseType(StatusCodes.Status204NoContent)]
+		[ProducesResponseType(StatusCodes.Status404NotFound)]
+		public async Task<ActionResult<Season>> GetSeason(Identifier identifier)
 		{
-			Show ret = await _libraryManager.GetOrDefault<Show>(showSlug);
+			Season ret = await _libraryManager.GetOrDefault(identifier.IsContainedIn<Season, Episode>(x => x.Episodes));
-			if (ret == null)
+			if (ret != null)
-				return NotFound();
+				return ret;
-			return ret;
+			Episode episode = await identifier.Match(
+				id => _libraryManager.GetOrDefault<Episode>(id),
+				slug => _libraryManager.GetOrDefault<Episode>(slug)
+			);
+			return episode == null
+				? NotFound()
+				: NoContent();
 		}
 
-		[HttpGet("{showID:int}-{seasonNumber:int}e{episodeNumber:int}/show")]
+		/// <summary>
+		/// Get tracks
+		/// </summary>
+		/// <remarks>
+		/// List the tracks (video, audio and subtitles) available for this episode.
+		/// This endpoint provide the list of raw tracks, without transcode on it. To get a schema easier to watch
+		/// on a player, see the [/watch endpoint](#/watch).
+		/// </remarks>
+		/// <param name="identifier">The ID or slug of the <see cref="Episode"/>.</param>
+		/// <param name="sortBy">A key to sort tracks by.</param>
+		/// <param name="where">An optional list of filters.</param>
+		/// <param name="limit">The number of tracks to return.</param>
+		/// <param name="afterID">An optional track's ID to start the query from this specific item.</param>
+		/// <returns>A page of tracks.</returns>
+		/// <response code="400">The filters or the sort parameters are invalid.</response>
+		/// <response code="404">No track with the given ID or slug could be found.</response>
+		/// TODO fix the /watch endpoint link (when operations ID are specified).
+		[HttpGet("{identifier:id}/tracks")]
+		[HttpGet("{identifier:id}/track", Order = AlternativeRoute)]
 		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Show>> GetShow(int showID, int seasonNumber, int episodeNumber)
+		[ProducesResponseType(StatusCodes.Status200OK)]
-		{
+		[ProducesResponseType(StatusCodes.Status400BadRequest, Type = typeof(RequestError))]
-			Show ret = await _libraryManager.GetOrDefault<Show>(showID);
+		[ProducesResponseType(StatusCodes.Status404NotFound)]
-			if (ret == null)
+		public async Task<ActionResult<Page<Track>>> GetEpisode(Identifier identifier,
-				return NotFound();
-			return ret;
-		}
-
-		[HttpGet("{episodeID:int}/season")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Season>> GetSeason(int episodeID)
-		{
-			Season ret = await _libraryManager.GetOrDefault<Season>(x => x.Episodes.Any(y => y.ID == episodeID));
-			if (ret == null)
-				return NotFound();
-			return ret;
-		}
-
-		[HttpGet("{showSlug}-s{seasonNumber:int}e{episodeNumber:int}/season")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Season>> GetSeason(string showSlug, int seasonNumber, int episodeNumber)
-		{
-			try
-			{
-				return await _libraryManager.Get(showSlug, seasonNumber);
-			}
-			catch (ItemNotFoundException)
-			{
-				return NotFound();
-			}
-		}
-
-		[HttpGet("{showID:int}-{seasonNumber:int}e{episodeNumber:int}/season")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Season>> GetSeason(int showID, int seasonNumber, int episodeNumber)
-		{
-			try
-			{
-				return await _libraryManager.Get(showID, seasonNumber);
-			}
-			catch (ItemNotFoundException)
-			{
-				return NotFound();
-			}
-		}
-
-		[HttpGet("{episodeID:int}/track")]
-		[HttpGet("{episodeID:int}/tracks")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Page<Track>>> GetEpisode(int episodeID,
 			[FromQuery] string sortBy,
-			[FromQuery] int afterID,
 			[FromQuery] Dictionary<string, string> where,
-			[FromQuery] int limit = 30)
+			[FromQuery] int limit = 30,
+			[FromQuery] int? afterID = null)
 		{
 			try
 			{
 				ICollection<Track> resources = await _libraryManager.GetAll(
-					ApiHelper.ParseWhere<Track>(where, x => x.Episode.ID == episodeID),
+					ApiHelper.ParseWhere(where, identifier.Matcher<Track>(x => x.EpisodeID, x => x.Episode.Slug)),
 					new Sort<Track>(sortBy),
 					new Pagination(limit, afterID));
 
-				if (!resources.Any() && await _libraryManager.GetOrDefault<Episode>(episodeID) == null)
+				if (!resources.Any() && await _libraryManager.GetOrDefault(identifier.IsSame<Episode>()) == null)
 					return NotFound();
 				return Page(resources, limit);
 			}
 			catch (ArgumentException ex)
 			{
-				return BadRequest(new { Error = ex.Message });
+				return BadRequest(new RequestError(ex.Message));
-			}
-		}
-
-		[HttpGet("{showID:int}-s{seasonNumber:int}e{episodeNumber:int}/track")]
-		[HttpGet("{showID:int}-s{seasonNumber:int}e{episodeNumber:int}/tracks")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Page<Track>>> GetEpisode(int showID,
-			int seasonNumber,
-			int episodeNumber,
-			[FromQuery] string sortBy,
-			[FromQuery] int afterID,
-			[FromQuery] Dictionary<string, string> where,
-			[FromQuery] int limit = 30)
-		{
-			try
-			{
-				ICollection<Track> resources = await _libraryManager.GetAll(
-					ApiHelper.ParseWhere<Track>(where, x => x.Episode.ShowID == showID
-					                                        && x.Episode.SeasonNumber == seasonNumber
-					                                        && x.Episode.EpisodeNumber == episodeNumber),
-					new Sort<Track>(sortBy),
-					new Pagination(limit, afterID));
-
-				if (!resources.Any() && await _libraryManager.GetOrDefault(showID, seasonNumber, episodeNumber) == null)
-					return NotFound();
-				return Page(resources, limit);
-			}
-			catch (ArgumentException ex)
-			{
-				return BadRequest(new { Error = ex.Message });
-			}
-		}
-
-		[HttpGet("{slug}-s{seasonNumber:int}e{episodeNumber:int}/track")]
-		[HttpGet("{slug}-s{seasonNumber:int}e{episodeNumber:int}/tracks")]
-		[PartialPermission(Kind.Read)]
-		public async Task<ActionResult<Page<Track>>> GetEpisode(string slug,
-			int seasonNumber,
-			int episodeNumber,
-			[FromQuery] string sortBy,
-			[FromQuery] int afterID,
-			[FromQuery] Dictionary<string, string> where,
-			[FromQuery] int limit = 30)
-		{
-			try
-			{
-				ICollection<Track> resources = await _libraryManager.GetAll(
-					ApiHelper.ParseWhere<Track>(where, x => x.Episode.Show.Slug == slug
-						&& x.Episode.SeasonNumber == seasonNumber
-						&& x.Episode.EpisodeNumber == episodeNumber),
-					new Sort<Track>(sortBy),
-					new Pagination(limit, afterID));
-
-				if (!resources.Any() && await _libraryManager.GetOrDefault(slug, seasonNumber, episodeNumber) == null)
-					return NotFound();
-				return Page(resources, limit);
-			}
-			catch (ArgumentException ex)
-			{
-				return BadRequest(new { Error = ex.Message });
-			}
-		}
-
-		[HttpGet("{id:int}/thumbnail")]
-		[HttpGet("{id:int}/backdrop")]
-		public async Task<IActionResult> GetThumb(int id)
-		{
-			try
-			{
-				Episode episode = await _libraryManager.Get<Episode>(id);
-				return _files.FileResult(await _thumbnails.GetImagePath(episode, Images.Thumbnail));
-			}
-			catch (ItemNotFoundException)
-			{
-				return NotFound();
-			}
-		}
-
-		[HttpGet("{slug}/thumbnail")]
-		[HttpGet("{slug}/backdrop")]
-		public async Task<IActionResult> GetThumb(string slug)
-		{
-			try
-			{
-				Episode episode = await _libraryManager.Get<Episode>(slug);
-				return _files.FileResult(await _thumbnails.GetImagePath(episode, Images.Thumbnail));
-			}
-			catch (ItemNotFoundException)
-			{
-				return NotFound();
 			}
 		}
 	}

src/Kyoo.Core/Views/SeasonApi.cs

@@ -40,7 +40,7 @@ namespace Kyoo.Core.Api
 	[Route("api/season", Order = AlternativeRoute)]
 	[ApiController]
 	[PartialPermission(nameof(SeasonApi))]
-	[ApiDefinition("Seasons", Group = ResourceGroup)]
+	[ApiDefinition("Seasons", Group = ResourcesGroup)]
 	public class SeasonApi : CrudThumbsApi<Season>
 	{
 		/// <summary>

src/Kyoo.Core/Views/ShowApi.cs

@@ -44,7 +44,7 @@ namespace Kyoo.Core.Api
 	[Route("api/movies", Order = AlternativeRoute)]
 	[ApiController]
 	[PartialPermission(nameof(ShowApi))]
-	[ApiDefinition("Shows", Group = ResourceGroup)]
+	[ApiDefinition("Shows", Group = ResourcesGroup)]
 	public class ShowApi : CrudThumbsApi<Show>
 	{
 		/// <summary>