Skip to content

sok.config.api_registry

API Registry - Centralized configuration of API services

This file centralizes all API configurations to facilitate adding new services in the future.

To add a new API:

  1. Add an entry in API_SERVICES
  2. Create the authentication class in oauth_providers.py (if OAuth required)
  3. Create the API class in the appropriate apis/ folder

APIGroup

class APIGroup

Bases: Enum

API constraint group for categorization.

Source

Attributes

NameDescription
API_KEY

API key required.

AUTH

Account and login required.

FREE

No API key required.

RESTRICTIVE

Limited or restrictive access.

APIServiceConfigdataclass

class APIServiceConfig(
id: str,
name: str,
description: str,
media_type: str,
auth_type: AuthType,
group: APIGroup,
config_key: str,
session_key: str = '',
api_key_url: str = '',
base_url: str = '',
env_var: str = '',
requires_secret: bool = False,
secret_config_key: str = '',
icon: str = '',
enabled: bool = True,
)

API service configuration dataclass.

Parameters

NameTypeDefaultDescription
idstrUnique service identifier.
namestrDisplay name of the service.
descriptionstrBrief description of the service.
media_typestrType of media handled (video, music, etc.).
auth_typeAuthTypeAuthentication type required.
groupAPIGroupAPI constraint group.
config_keystrKey for storing API credentials in config.
session_keystr''Key for session storage.
api_key_urlstr''URL to obtain API key.
base_urlstr''Base URL for API requests.
env_varstr''Environment variable name.
requires_secretboolFalseWhether a client secret is required.
secret_config_keystr''Key for storing client secret.
iconstr''Icon identifier for UI.
enabledboolTrueWhether the service is enabled.
Source

Attributes

NameTypeDescription
api_key_urlstr

URL to obtain API key.

auth_typeAuthType

Authentication type required.

base_urlstr

Base URL for API requests.

config_keystr

Key for storing API credentials in config.

descriptionstr

Brief description of the service.

enabledbool

Whether the service is enabled.

env_varstr

Environment variable name.

groupAPIGroup

API constraint group.

iconstr

Icon identifier for UI.

idstr

Unique service identifier.

media_typestr

Type of media handled (video, music, etc.).

namestr

Display name of the service.

requires_secretbool

Whether a client secret is required.

secret_config_keystr

Key for storing client secret.

session_keystr

Key for session storage.

AuthType

class AuthType

Bases: Enum

Authentication type required by the API.

Source

Attributes

NameDescription
API_KEY

Simple API key authentication.

BEARER

Bearer token authentication.

OAUTH

OAuth 2.0 flow authentication.

SESSION

Session-based authentication.

Functions

get_all_config_keys

def get_all_config_keys() -> Dict[str, str]:

Return a service_id to config_key mapping for all services.

Returns

  • Dict[str, str]Dictionary mapping service IDs to their config keys.
Source

get_all_env_vars

def get_all_env_vars() -> Dict[str, str]:

Return a config_key to env_var mapping for .env loading.

Returns

  • Dict[str, str]Dictionary mapping config keys to environment variable names.
Source

get_all_services

def get_all_services() -> List[APIServiceConfig]:

Retrieve all enabled services.

Returns

Source

get_enabled_services

def get_enabled_services() -> List[APIServiceConfig]:

Retrieve all enabled services.

Returns

Source

get_oauth_services

def get_oauth_services() -> List[APIServiceConfig]:

Retrieve all services requiring OAuth or Session authentication.

Returns

Source

get_service

def get_service(service_id: str) -> Optional[APIServiceConfig]:

Retrieve a service configuration by its ID.

Parameters

NameTypeDescription
service_idstrUnique identifier of the service.

Returns

Source

get_services_by_category

def get_services_by_category() -> Dict[str, List[APIServiceConfig]]:

Retrieve all services grouped by category.

Returns

  • Dict[str, List[APIServiceConfig]]Dictionary with categories as keys and list of services as values.
  • Dict[str, List[APIServiceConfig]]Order is defined by CATEGORY_ORDER.
Source

get_services_by_media_type

def get_services_by_media_type(media_type: str) -> List[APIServiceConfig]:

Retrieve all services for a media type.

Parameters

NameTypeDescription
media_typestrType of media (video, music, books, games).

Returns

Source

Attributes

NameTypeValue
API_SERVICESDict[str, APIServiceConfig]{'tmdb': APIServiceConfig(id='tmdb', name='TMDB', description='Movie and TV series metadata', media_type='video', auth_type=AuthType.API_KEY, group=APIGroup.API_KEY, config_key='api_key_tmdb_v4', session_key='', api_key_url='https://www.themoviedb.org/settings/api', base_url='https://api.themoviedb.org/3/', env_var='API_KEY_TMDB_V4', icon=''), 'tvdb': APIServiceConfig(id='tvdb', name='TVDB', description='TV series metadata', media_type='video', auth_type=AuthType.API_KEY, group=APIGroup.API_KEY, config_key='api_key_tvdb', session_key='', api_key_url='https://thetvdb.com/api-information', base_url='https://api4.thetvdb.com/v4/', env_var='API_KEY_TVDB', icon=''), 'omdb': APIServiceConfig(id='omdb', name='OMDb', description='Open Movie Database (IMDb)', media_type='video', auth_type=AuthType.API_KEY, group=APIGroup.RESTRICTIVE, config_key='api_key_omdb', api_key_url='https://www.omdbapi.com/apikey.aspx', base_url='https://www.omdbapi.com/', env_var='API_KEY_OMDB', icon=''), 'lastfm': APIServiceConfig(id='lastfm', name='Last.fm', description='Music metadata and scrobbling', media_type='music', auth_type=AuthType.API_KEY, group=APIGroup.API_KEY, config_key='api_key_lastfm', api_key_url='https://www.last.fm/api/account/create', base_url='https://ws.audioscrobbler.com/2.0/', env_var='API_KEY_LASTFM', icon=''), 'spotify': APIServiceConfig(id='spotify', name='Spotify', description='Spotify music metadata', media_type='music', auth_type=AuthType.OAUTH, group=APIGroup.AUTH, config_key='spotify_client_id', session_key='spotify_session', api_key_url='https://developer.spotify.com/dashboard', base_url='https://api.spotify.com/v1/', env_var='SPOTIFY_CLIENT_ID', requires_secret=True, secret_config_key='spotify_client_secret', icon=''), 'deezer': APIServiceConfig(id='deezer', name='Deezer', description='Music metadata (free)', media_type='music', auth_type=AuthType.API_KEY, group=APIGroup.FREE, config_key='', api_key_url='', base_url='https://api.deezer.com/', env_var='', icon=''), 'musicbrainz': APIServiceConfig(id='musicbrainz', name='MusicBrainz', description='Open music database', media_type='music', auth_type=AuthType.API_KEY, group=APIGroup.FREE, config_key='', api_key_url='', base_url='https://musicbrainz.org/ws/2/', env_var='', icon=''), 'google_books': APIServiceConfig(id='google_books', name='Google Books', description='Google Books metadata', media_type='books', auth_type=AuthType.API_KEY, group=APIGroup.FREE, config_key='google_books_api_key', api_key_url='https://console.cloud.google.com/apis/credentials', base_url='https://www.googleapis.com/books/v1/', env_var='GOOGLE_BOOKS_API_KEY', icon=''), 'openlibrary': APIServiceConfig(id='openlibrary', name='Open Library', description='Open library (free)', media_type='books', auth_type=AuthType.API_KEY, group=APIGroup.FREE, config_key='', api_key_url='', base_url='https://openlibrary.org/', env_var='', icon=''), 'igdb': APIServiceConfig(id='igdb', name='IGDB', description='Game metadata (via Twitch)', media_type='games', auth_type=AuthType.OAUTH, group=APIGroup.AUTH, config_key='igdb_client_id', session_key='igdb_session', api_key_url='https://dev.twitch.tv/console/apps', base_url='https://api.igdb.com/v4/', env_var='IGDB_CLIENT_ID', requires_secret=True, secret_config_key='igdb_client_secret', icon=''), 'rawg': APIServiceConfig(id='rawg', name='RAWG', description='Video game database', media_type='games', auth_type=AuthType.API_KEY, group=APIGroup.FREE, config_key='api_key_rawg', api_key_url='https://rawg.io/apidocs', base_url='https://api.rawg.io/api/', env_var='API_KEY_RAWG', icon=''), 'fanart': APIServiceConfig(id='fanart', name='Fanart.tv', description='High quality artwork', media_type='images', auth_type=AuthType.API_KEY, group=APIGroup.API_KEY, config_key='api_key_fanart', api_key_url='https://fanart.tv/get-an-api-key/', base_url='https://webservice.fanart.tv/v3/', env_var='API_KEY_FANART', icon='')}
CATEGORY_LABELS{'video': ('category_video', 'Video (Movies & Series)'), 'music': ('category_music', 'Music'), 'books': ('category_books', 'Books'), 'games': ('category_games', 'Video Games'), 'images': ('category_images', 'Artwork & Images'), 'other': ('category_other', 'Other services')}
CATEGORY_ORDER['video', 'music', 'books', 'games', 'images', 'other']
GROUP_LABELS{APIGroup.FREE: ('api_group_free', 'Free (No key required)'), APIGroup.API_KEY: ('api_group_api_key', 'API Key Required'), APIGroup.AUTH: ('api_group_auth', 'Account & Login Required'), APIGroup.RESTRICTIVE: ('api_group_restrictive', 'Restrictive / Limited')}
GROUP_ORDER[APIGroup.FREE, APIGroup.API_KEY, APIGroup.AUTH, APIGroup.RESTRICTIVE]
Built with Kiln