diff --git a/Sources/Services/AmiiboService.swift b/Sources/Services/AmiiboService.swift index de83f3b..79b7fe5 100644 --- a/Sources/Services/AmiiboService.swift +++ b/Sources/Services/AmiiboService.swift @@ -1,6 +1,9 @@ import Foundation -public struct AmiiboService { +/// This service provides the interface to make remote API calls to the [Amiibo API](https://www.amiiboapi.com) and, subsequently, handle its responses. +/// +/// Given that this remote service is a read-only API, this service will exclusively return decoded models or entities in cases the requests are successful, or it will throw errors otherwise. +public actor AmiiboService { // MARK: Properties @@ -8,7 +11,9 @@ public struct AmiiboService { // MARK: Initialisers - init(configuration: URLSessionConfiguration) { + /// Initialises this service. + /// - Parameter configuration: The `URLSessionConfiguration` configuration to use to set this service. + public init(configuration: URLSessionConfiguration) { self.client = .init(configuration: configuration) } @@ -20,6 +25,10 @@ extension AmiiboService: Service { // MARK: Functions + /// Retrieves a list of amiibos from a remote location that matches a given filter criteria. + /// - Parameter filter: A ``AmiiboFilter`` instance that contains the filtering criteria. + /// - Returns: A list of decoded ``Amiibo`` instances that matches the given filter criteria. + /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed. public func amiibos( filter: AmiiboFilter = .init() ) async throws -> [Amiibo] { @@ -31,6 +40,10 @@ extension AmiiboService: Service { ).items } + /// Retrieves a list of amiibo series from a remote location that matches a given filter criteria. + /// - Parameter filter: A ``AmiiboSeriesFilter`` instance that contains the filtering criteria. + /// - Returns: A list of decoded ``AmiiboSeries`` instances that matches the given filter criteria. + /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed. public func amiiboSeries( filter: AmiiboSeriesFilter = .init() ) async throws -> [AmiiboSeries] { @@ -42,6 +55,10 @@ extension AmiiboService: Service { ).items } + /// Retrieves a list of amiibo types from a remote location that matches a given filter criteria. + /// - Parameter filter: A ``AmiiboTypeFilter`` instance that contains the filtering criteria. + /// - Returns: A list of decoded ``AmiiboType`` instances that matches the given filter criteria. + /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed. public func amiiboTypes( filter: AmiiboTypeFilter = .init() ) async throws -> [AmiiboType] { @@ -53,6 +70,10 @@ extension AmiiboService: Service { ).items } + /// Retrieves a list of characters from a remote location that matches a given filter criteria. + /// - Parameter filter: A ``CharacterFilter`` instance that contains the filtering criteria. + /// - Returns: A list of decoded ``Character`` instances that matches the given filter criteria. + /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed. public func characters( filter: CharacterFilter = .init() ) async throws -> [Character] { @@ -64,6 +85,10 @@ extension AmiiboService: Service { ).items } + /// Retrieves a list of game series from a remote location that matches a given filter criteria. + /// - Parameter filter: A ``GameSeriesFilter`` instance that contains the filtering criteria. + /// - Returns: A list of decoded ``GameSeries`` instances that matches the given filter criteria. + /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed. public func gameSeries( filter: GameSeriesFilter = .init() ) async throws -> [GameSeries] { @@ -75,6 +100,9 @@ extension AmiiboService: Service { ).items } + /// Retrieves the date in which the remote API was last updated. + /// - Returns: A `Date` instance that represents the date in which the remote API was last updated. + /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed. public func lastUpdated() async throws -> Date { client.setDateDecodingStrategy(.formatted(.dateAndTime))