feat(about): artist descriptions from Wikipedia
- GET /artists/{id}/description shows what Wikipedia says about an artist: a short
text with its page, a link and the licence (CC BY-SA 4.0).
- New provider "wikipedia" (off by default, no key, contact in the User-Agent, which
Wikimedia requires). The way to the text is a chain of ids, never a name: the
artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the Wikipedia
page Wikidata names in the first configured language that has one. A page is used
only if it is an article about that same item.
- [wikipedia] languages in the config (one to five codes of two or three lower case
letters, checked before they are sent: an unknown site makes Wikidata answer with
every language).
- Stored 30 days (a day when there was nothing to find), served stale if Wikipedia
fails, removed with the provider's data (the purge now reports descriptions).
- MusicBrainz client: WikidataID. Wikipedia client for Wikidata and the summary,
which also reads Wikidata's errors that come with HTTP 200.
- artist_descriptions table (migration 0014, SQLite and PostgreSQL).
- Spec, contract test, README and example config updated.
Closes #39
This commit is contained in:
parent
c91b88a83e
commit
48cb903115
1 changed files with 2124 additions and 19 deletions
|
|
@ -928,6 +928,46 @@ paths:
|
|||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||||
|
||||
/artists/{id}/description:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/Id'}
|
||||
get:
|
||||
tags: [Discovery]
|
||||
operationId: getArtistDescription
|
||||
summary: What Wikipedia says about an artist
|
||||
description: |
|
||||
A short text about the artist from Wikipedia, with the page it comes from. The way to it
|
||||
is a chain of identifiers, never a search by name: the artist's MusicBrainz id, then the
|
||||
Wikidata item that MusicBrainz links to it, then the Wikipedia page that Wikidata names in
|
||||
the first of the server's languages (`[wikipedia] languages`) that has one. A page is used
|
||||
only if it is an article about that same item (not a page of disambiguation). An artist
|
||||
with no MusicBrainz id answers `no_id`: Sonda does not look an id up by name.
|
||||
|
||||
It needs the `wikipedia` provider, which an admin switches on; nothing is sent while it is
|
||||
off (`disabled`). What is sent: the MusicBrainz id to MusicBrainz, the Wikidata item to
|
||||
Wikidata, the title of the page to Wikipedia, and your server's IP address and a
|
||||
`User-Agent` with the contact of the admin to all three. The answer is stored: 30 days, or a
|
||||
day when there was nothing to find, and an old one is returned as `stale` if Wikipedia
|
||||
fails. When there is nothing to show, `description` is `null` and `provider_status` is
|
||||
`ok`.
|
||||
|
||||
The text is CC BY-SA 4.0. Where you show it, name the page (`title`), link to it (`url`) and
|
||||
give the licence (`license`, `license_url`), and say if you changed it.
|
||||
security: [{bearerAuth: []}]
|
||||
responses:
|
||||
'200':
|
||||
description: The description, or `null` with the status that says why.
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/ArtistDescription'}
|
||||
'400': {$ref: '#/components/responses/InvalidInput'}
|
||||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||||
'404':
|
||||
description: No such artist (`artist_not_found`).
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/Error'}
|
||||
|
||||
/albums:
|
||||
get:
|
||||
tags: [Catalog]
|
||||
|
|
@ -1265,7 +1305,7 @@ paths:
|
|||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema: {type: string, enum: [lastfm, musicbrainz]}
|
||||
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
|
||||
put:
|
||||
tags: [Providers]
|
||||
operationId: updateProvider
|
||||
|
|
@ -1303,7 +1343,7 @@ paths:
|
|||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema: {type: string, enum: [lastfm, musicbrainz]}
|
||||
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
|
||||
post:
|
||||
tags: [Providers]
|
||||
operationId: testProvider
|
||||
|
|
@ -1338,7 +1378,7 @@ paths:
|
|||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema: {type: string, enum: [lastfm, musicbrainz]}
|
||||
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
|
||||
delete:
|
||||
tags: [Providers]
|
||||
operationId: purgeProviderData
|
||||
|
|
@ -1799,7 +1839,7 @@ components:
|
|||
additionalProperties: false
|
||||
required: [name, enabled, needs_api_key, has_api_key, contact, sends, notes, updated_at]
|
||||
properties:
|
||||
name: {type: string, enum: [lastfm, musicbrainz]}
|
||||
name: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
|
||||
enabled: {type: boolean, description: Whether Sonda may contact this provider.}
|
||||
needs_api_key: {type: boolean}
|
||||
has_api_key: {type: boolean, description: Whether a key is stored. The key itself is never returned.}
|
||||
|
|
@ -1829,12 +1869,47 @@ components:
|
|||
maxLength: 200
|
||||
description: A URL or e-mail address, without parentheses. Empty restores the default.
|
||||
|
||||
ArtistDescription:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [provider, provider_status, stale, retrieved_at, attribution, description]
|
||||
properties:
|
||||
provider: {type: string, enum: [wikipedia]}
|
||||
provider_status:
|
||||
type: string
|
||||
enum: [ok, disabled, error, no_id]
|
||||
description: |
|
||||
`ok` when the stored answer is as fresh as it needs to be (which can be "nothing found");
|
||||
`disabled` when the provider is off; `error` when Wikipedia could not be asked; `no_id`
|
||||
when the artist has no MusicBrainz id.
|
||||
stale: {type: boolean, description: True when the description is older than it should be because Wikipedia could not be asked.}
|
||||
retrieved_at: {type: string, format: date-time, nullable: true, description: When it was read; null when nothing is known.}
|
||||
attribution: {type: string, description: What to show where the text is shown.}
|
||||
description:
|
||||
nullable: true
|
||||
allOf:
|
||||
- {$ref: '#/components/schemas/Description'}
|
||||
|
||||
Description:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [text, short, language, title, url, license, license_url]
|
||||
properties:
|
||||
text: {type: string, description: "The first paragraph of the article, plain text, at most 4000 characters."}
|
||||
short: {type: string, description: "One line, like \"gruppo musicale inglese\". May be empty."}
|
||||
language: {type: string, description: "The language of the page, like `it`."}
|
||||
title: {type: string, description: "The title of the page."}
|
||||
url: {type: string, format: uri, description: "The page, on Wikipedia."}
|
||||
license: {type: string, description: "The licence of the text."}
|
||||
license_url: {type: string, format: uri}
|
||||
|
||||
ProviderPurge:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [similar_artists, tags, artists]
|
||||
required: [similar_artists, tags, descriptions, artists]
|
||||
properties:
|
||||
similar_artists: {type: integer, description: Similar-artist links removed.}
|
||||
descriptions: {type: integer, description: Artist descriptions removed (only the data of Wikipedia has any).}
|
||||
tags: {type: integer, description: Tags removed.}
|
||||
artists: {type: integer, description: "Artists removed because only the removed data named them and nobody has files for them."}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue