rock-n-code/amiibo-service
1
0
Fork 0
Code Issues Pull Requests Actions Releases 15 Activity

Open API specification improvements and License update (#17)

Browse Source 
This PR contains the work done to:
* improve the overall `OpenAPI` specification documentation describing the `Amiibo API` service;
* update the `AmiiboFilter` type to include the `head` and `tail` properties;
* update the error handling of the errors coming up from the service;
* update its license to Apache v2.0;
* regenerate the Github Pages documentation.

Reviewed-on: #17
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
This commit was merged in pull request #17.
This commit is contained in:
Javier Cicchelli
2025-10-07 22:07:55 +00:00
committed by Javier Cicchelli
parent c303e1f8f3
commit 40afefed15
127 changed files with 676 additions and 583 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift
+12
View File
@@ -182,10 +182,12 @@ private extension AmiiboLiveClient {
amiiboSeries: filter.series,
character: filter.gameCharacter,
gameseries: filter.gameSeries,
head: filter.head,
id: filter.identifier,
name: filter.name,
showgames: filter.showGames,
showusage: filter.showUsage,
tail: filter.tail,
_type: filter.type
)))
} catch {
@@ -200,6 +202,10 @@ private extension AmiiboLiveClient {
}
case .badRequest:
throw AmiiboServiceError.badRequest
case .notFound:
throw AmiiboServiceError.notFound
case .internalServerError:
throw AmiiboServiceError.notAvailable
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
@@ -363,6 +369,12 @@ private extension AmiiboLiveClient {
case let .json(output):
return output.lastUpdated
}
case .badRequest:
throw AmiiboServiceError.badRequest
case .notFound:
throw AmiiboServiceError.notFound
case .internalServerError:
throw AmiiboServiceError.notAvailable
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
Sources/AmiiboService/Public/Filters/AmiiboFilter.swift
+24 -12
View File
@@ -15,19 +15,22 @@ public struct AmiiboFilter: Sendable {
// MARK: Properties
/// A game character to return, if any.
/// A game character to filter the result, if any.
public let gameCharacter: String?
/// A game series to return, if any.
/// A game series to filter the result, if any.
public let gameSeries: String?
/// A first part of an identifier to filter the result, if any.
public let head: String?
/// An amiibo identifier to return, if any.
/// An amiibo identifier to filter the result, if any.
public let identifier: String?
/// An amiibo name to return, if any.
/// An amiibo name to filter the result, if any.
public let name: String?
/// An amiibo series to return, if any.
/// An amiibo series to filter the result, if any.
public let series: String?
/// A flag indicating whether to include games in the response, if any.
@@ -35,23 +38,30 @@ public struct AmiiboFilter: Sendable {
/// A flag indicating whether to include amiibo usages in games in the response, if any.
public let showUsage: Bool?
/// A last part of an identifier to filter the result, if any.
public let tail: String?
/// An amiibo type to return, if any.
/// An amiibo type to filter the result, if any.
public let type: String?
// MARK: Initializers
/// Initializes this filter.
/// - Parameters:
/// - identifier: An amiibo identifier to return, if any.
/// - name: An amiibo name to return, if any.
/// - type: An amiibo type to return, if any.
/// - series: An amiibo series to return, if any.
/// - gameCharacter: A game character to return, if any.
/// - gameSeries: A game series to return, if any.
/// - head: A first part of an identifier to filter the result, if any.
/// - tail: A last part of an identifier to filter the result, if any.
/// - identifier: An amiibo identifier to filter the result, if any.
/// - name: An amiibo name to filter the result, if any.
/// - type: An amiibo type to filter the result, if any.
/// - series: An amiibo series to filter the result, if any.
/// - gameCharacter: A game character to filter the result, if any.
/// - gameSeries: A game series to filter the result, if any.
/// - showGames: A flag indicating whether to include games in the response, if any.
/// - showUsage: A flag indicating whether to include amiibo usages in games in the response, if any.
public init(
head: String? = nil,
tail: String? = nil,
identifier: String? = nil,
name: String? = nil,
type: String? = nil,
@@ -63,11 +73,13 @@ public struct AmiiboFilter: Sendable {
) {
self.gameCharacter = gameCharacter
self.gameSeries = gameSeries
self.head = head
self.identifier = identifier
self.name = name
self.series = series
self.showGames = showGames
self.showUsage = showUsage
self.tail = tail
self.type = type
}
Sources/AmiiboService/openapi.yaml
+173 -74
View File
@@ -10,103 +10,156 @@
#
# ===----------------------------------------------------------------------===
openapi: '3.1.0'
openapi: '3.1.1'
info:
title: Amiibo API service
description: The Amiibo API RESTful service.
version: 1.0.0
title: Amiibo API
summary: A RESTFul API for Amiibo.
description: |
# information
_AmiiboAPI_ is primarily used for educational purposes.
This is a **reading-only API**. Only HTTP GET method is allowed by this API.
**No authentication** is required to use this API. All resources are allowed to access.
If you are going to be calling this API regularly. We recommend that you use **caching** on your system.
# Terms & Conditions
By using our API, you hereby accepted the following terms and conditions:
* *This API has no affiliation with Nintendo or any other companies that own the rights to it.*
* *Other reports collected by the respective companies that own the rights are not our responsibility.*
* *User agrees that the use of this API is entirely at user's own risks.*
* *You will require your end users to comply with (and not knowingly enable them to violate) applicable law, regulation, and the Terms.*
* *You will comply with all applicable law, regulation, and third party rights (including without limitation laws regarding the import or export of data or software, privacy, and local laws). You will not use the APIs to encourage or promote illegal activity or violation of third party rights.*
* *These Terms and Conditions are subject to change without notice, from time to time in our sole discretion.*
version: v1.0.0
termsOfService: https://www.amiiboapi.com/docs/#termscondition
contact:
name: FAQ
url: https://www.amiiboapi.com/faq/
license:
name: MIT license
identifier: MIT
servers:
- url: https://www.amiiboapi.com/api
description: Amiibo API service (live)
description: Live service
tags:
- name: Amiibo
description: Amiibo-related endpoints.
- name: Game
description: Game-related endpoints.
- name: Service
description: Service-related endpoints.
externalDocs:
url: https://www.amiiboapi.com/docs
description: Amiibo API documentation
paths:
/amiibo:
get:
summary: Get a list of Amiibo items.
description: Get a list of all the Amiibo items available in the database.
operationId: getAmiibos
tags:
- Amiibo
responses:
'200':
description: Successful response returning the object that contains a list of Amiibo items.
description: Response that retuns a decodable JSON object wrapping a list of Amiibo items.
content:
application/json:
schema:
$ref: '#/components/schemas/AmiiboWrapper'
'400':
description: Bad Amiibo request.
description: An amiibo bad request.
'404':
description: An amiibo not found.
'500':
description: Service is not available.
parameters:
- name: amiiboSeries
in: query
description: The Amiibo series identifier or name to filter the response.
description: An identifier or name of an Amiibo to filter the response.
required: false
schema:
type: string
style: form
- name: character
in: query
description: The game character identifier or name to filter the response.
description: An identifier or name of a game character to filter the response.
required: false
schema:
type: string
style: form
- name: gameseries
in: query
description: The game series identifier or name to filter the response.
description: An identifier or name of a game series to filter the response.
required: false
schema:
type: string
style: form
- name: head
in: query
description: A last part of an identifier to filter the response.
required: false
schema:
type: string
style: form
- name: id
in: query
description: The Amiibo identifier to filter the response.
description: An identifier of an Amiibo to filter the response.
required: false
schema:
type: string
style: form
- name: name
in: query
description: The Amiibo name to filter the response.
description: A name of an Amiibo to filter the response.
required: false
schema:
type: string
style: form
- name: showgames
in: query
description: The flag that indicates whether to include information about related games.
description: A flag that indicates whether to include information about related games.
required: false
schema:
type: boolean
style: form
- name: showusage
in: query
description: The flag that indicates whether to include information about Amiibo usage in related games.
description: A flag that indicates whether to include information about Amiibo usage in related games.
required: false
schema:
type: boolean
style: form
- name: type
- name: tail
in: query
description: The Amiibo type to filter the response.
description: A first part of an identifier to filter the response.
required: false
schema:
type: string
style: form
- name: type
in: query
description: An identifier or a name of an Amiibo type to filter the response.
required: false
schema:
type: string
style: form
/amiiboseries:
get:
description: Get a list of all the Amiibo series available in the database.
operationId: getAmiiboSeries
tags:
- Amiibo
responses:
'200':
description: Successful response returning the object that contains a list of Amiibo series.
content:
application/json:
schema:
$ref: '#/components/schemas/TupleWrapper'
$ref: '#/components/responses/SuccessTuple'
'400':
description: Bad Amiibo series request.
description: An amiibo series bad request.
'404':
description: Amiibo series not found.
description: An amiibo series not found.
'500':
description: Service currently not available.
description: Service is not available.
parameters:
- name: key
in: query
@@ -122,24 +175,21 @@ paths:
schema:
type: string
style: form
/character:
get:
description: Get a list of all the game characters available in the database.
operationId: getGameCharacters
tags:
- Game
responses:
'200':
description: Successful response returning the object that contains a list of game characters.
content:
application/json:
schema:
$ref: '#/components/schemas/TupleWrapper'
$ref: '#/components/responses/SuccessTuple'
'400':
description: Bad game character request.
description: A game character bad request.
'404':
description: Game character not found.
description: A game character not found.
'500':
description: Service currently not available.
description: Service is not available.
parameters:
- name: key
in: query
@@ -155,24 +205,21 @@ paths:
schema:
type: string
style: form
/gameseries:
get:
description: Gets a list of all the game series available in the database.
operationId: getGameSeries
tags:
- Game
responses:
'200':
description: Successful response returning the object that contains a list of game series.
content:
application/json:
schema:
$ref: '#/components/schemas/TupleWrapper'
$ref: '#/components/responses/SuccessTuple'
'400':
description: Bad game series request.
description: A game series bad request.
'404':
description: Game series not found.
description: A game series not found.
'500':
description: Service currently not available.
description: Service is not available.
parameters:
- name: key
in: query
@@ -188,24 +235,21 @@ paths:
schema:
type: string
style: form
/type:
get:
description: Gets a list of all the Amiibo types available in the database.
operationId: getAmiiboTypes
tags:
- Amiibo
responses:
'200':
description: Successful response returning the object that contains a list of Amiibo types.
content:
application/json:
schema:
$ref: '#/components/schemas/TupleWrapper'
$ref: '#/components/responses/SuccessTuple'
'400':
description: Bad Amiibo type request.
description: An amiibo type bad request.
'404':
description: Amiibo type not found.
description: An amiibo type not found.
'500':
description: Service currently not available.
description: Service is not available.
parameters:
- name: key
in: query
@@ -221,11 +265,12 @@ paths:
schema:
type: string
style: form
/lastupdated:
get:
description: Gets a timestamp when the Amiibo data was last updated.
operationId: getLastUpdated
tags:
- Service
responses:
'200':
description: Successful response returning the object that contains the date and time when the database was last updated.
@@ -233,42 +278,76 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/LastUpdated'
'400':
description: A last updated bad request.
'404':
description: A last updated not found.
'500':
description: Service is not available.
components:
responses:
SuccessTuple:
description: Response that returns a JSON object containing requested `Tuple` data from a resource.
content:
application/json:
schema:
$ref: '#/components/schemas/TupleWrapper'
schemas:
# Core Entities
Amiibo:
description: A type that contains all the information about an Amiibo.
type: object
properties:
amiiboSeries:
description: A name of the series the Amiibo belongs to.
type: string
character:
description: |
A name of a character of An Amiibo.
Multiple character have different amiibo design.
type: string
gameSeries:
description: A name of the game series the Amiibo belongs to.
type: string
games3DS:
description: A list of 3DS games an Amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
gamesSwitch:
description: A list of Switch games an Amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
gamesWiiU:
description: A list of Wii U games an Amiibo could be used in, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboGame'
head:
description: |
The first 8 characters of the hexadecimal value that identifies an Amiibo.
The positions 0 to 7 of the hexadecimal string.
type: string
image:
description: An image URL related to an Amiibo.
type: string
name:
description: A name of an Amiibo.
type: string
release:
type: object
description: A type that contains the release dates of an Amiibo, if any.
$ref: '#/components/schemas/AmiiboRelease'
tail:
description: |
The last 8 characters of the hexadecimal value that identifies an Amiibo.
The positions 8 to 15 of the hexadecimal string.
type: string
type:
description: A name for the type an Amiibo belongs to.
type: string
required:
- amiiboSeries
@@ -280,95 +359,115 @@ components:
- release
- tail
- type
AmiiboGame:
description: A type that represents a game in which an Amiibo is related to.
type: object
properties:
amiiboUsage:
description: A list of available usages an Amiibo have in a game, if any.
type: array
items:
$ref: '#/components/schemas/AmiiboUsage'
gameID:
description: A list of identifiers of a game an Amiibo is related to.
type: array
items:
type: string
gameName:
description: A name of a game an Amiibo is related to.
type: string
required:
- gameID
- gameName
AmiiboList:
description: A type that contains a list of `Amiibo` instances.
type: array
items:
description: A list if `Amiibo` instance.
$ref: '#/components/schemas/Amiibo'
AmiiboRelease:
description: A type that contains the release dates of an Amiibo throughout the world.
type: object
properties:
au:
description: A release date for Australia, if any.
type: string
format: date-time
eu:
description: A release date for Europe, if any.
type: string
format: date-time
jp:
description: A release date for Japan, if any.
type: string
format: date-time
na:
description: A release date for North America, if any.
type: string
format: date-time
AmiiboUsage:
description: A type that represents a use of an Amiibo in a game.
type: object
properties:
Usage:
description: An explanation of the usage of an Amiibo in a game.
type: string
write:
description: A flag that indicates whether the data in an Amiibo is writable or not.
type: boolean
required:
- Usage
- write
AmiiboWrapper:
LastUpdated:
description: A type that informs when the data in the service was last updated.
type: object
properties:
amiibo:
lastUpdated:
description: The date and time when the data in the database was last updated.
type: string
format: date-time
required:
- lastUpdated
# Wrapper Entities
AmiiboWrapper:
description: A type that contains either one or multiple `Amiibo` instances.
type: object
properties:
amiibo:
description: A property that contains one or multiple `Amiibo` instances.
oneOf:
- $ref: '#/components/schemas/Amiibo'
- $ref: '#/components/schemas/AmiiboList'
required:
- amiibo
LastUpdated:
type: object
properties:
lastUpdated:
type: string
format: date-time
required:
- lastUpdated
Tuple:
description: |
A type that is conformed only by the `key` and `name` properties.
This type represents either `AmiiboSeries`, `AmiiboType`, `GameCharacter`, and `GameSeries` types.
type: object
properties:
key:
description: A key assigned to a tuple.
type: string
name:
description: A name assigned to a tuple.
type: string
required:
- key
- name
TupleList:
description: A type that represents a list of key/value tuples.
type: array
items:
description: A property that can contains multiple `Tuple` instances.
$ref: '#/components/schemas/Tuple'
TupleWrapper:
description: A type that contains either one or multiple `Tuple` instances.
type: object
properties:
amiibo:
description: A property that contains one or multiple `Tuple` instances.
oneOf:
- $ref: '#/components/schemas/Tuple'
- $ref: '#/components/schemas/TupleList'