Skip to content

Services Reference

Reference for built-in services.

Built-in Services

All services inherit from BaseService (see Core Reference for details).

Hello Service

Simple demonstration service that returns a greeting message.

services.hello_service.HelloService 

HelloService(http_client: AsyncClient | None = None)

Bases: BaseService

Service that returns a simple hello world message.

This service demonstrates the simplest possible BaseService implementation. It doesn't require external API calls and returns a static response with optional customization via parameters.

The service accepts an optional 'name' parameter in the parameters dictionary. If not provided, defaults to "World".

Examples:

Example usage in endpoint configuration:

{
    "path": "/api/hello",
    "method": "GET",
    "service": "hello",
    "parameters": {
        "name": "Alice"
    }
}

Using the service directly:

service = HelloService()
result = await service.call({"name": "Alice"})
print(result["message"])  # "Hello, Alice!"
await service.cleanup()
Source code in core/services/base.py 
12
13
14
15
16
17
18
19
def __init__(self, http_client: httpx.AsyncClient | None = None):
    """Initialize service.

    Args:
        http_client: Optional HTTP client (will create one if not provided)
    """
    self._http_client = http_client
    self._owns_client = http_client is None

call async 

call(parameters: dict[str, Any] | None = None) -> dict[str, Any]

Return a hello world message.

Parameters:

  • parameters (dict[str, Any] | None, default: None ) –

    Optional service parameters dictionary containing:

    • name (str, optional): Name to greet. Defaults to "World".

Returns:

  • dict[str, Any] –

    Dictionary containing a greeting message with the following structure:

  • dict[str, Any] –

    ```python

  • dict[str, Any] –

    { "message": str, # e.g., "Hello, World!" "name": str, # The name parameter value "service": str # Service identifier

  • dict[str, Any] –

    }

  • dict[str, Any] –

    ```

Examples:

service = HelloService()
result = await service.call({"name": "Alice"})
print(result["message"])  # "Hello, Alice!"
await service.cleanup()
Source code in services/hello_service.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
async def call(self, parameters: dict[str, Any] | None = None) -> dict[str, Any]:
    """Return a hello world message.

    Args:
        parameters: Optional service parameters dictionary containing:

            - name (str, optional): Name to greet. Defaults to "World".

    Returns:
        Dictionary containing a greeting message with the following structure:

        ```python
        {
            "message": str,  # e.g., "Hello, World!"
            "name": str,     # The name parameter value
            "service": str   # Service identifier
        }
        ```

    Examples:
        ```python
        service = HelloService()
        result = await service.call({"name": "Alice"})
        print(result["message"])  # "Hello, Alice!"
        await service.cleanup()
        ```
    """
    # Extract name from parameters, defaulting to "World"
    name = "World"
    if parameters and "name" in parameters:
        provided_name = str(parameters["name"]).strip()
        if provided_name:
            name = provided_name

    # Return greeting response
    return {
        "message": f"Hello, {name}!",
        "name": name,
        "service": self.service_name,
    }

Crypto Service

Get cryptocurrency price data.

services.crypto_service.CryptoService 

CryptoService(http_client: AsyncClient | None = None)

Bases: BaseService

Service for cryptocurrency price data using CoinLore API.

This service provides access to real-time cryptocurrency market data through the CoinLore API. It implements the BaseService interface, making it compatible with the dynamic endpoint routing system.

The service accepts an optional 'symbol' parameter in the parameters dictionary. If not provided, defaults to "BTC" (Bitcoin).

Examples:

Example usage in endpoint configuration:

{
    "path": "/api/crypto",
    "method": "GET",
    "service": "crypto",
    "parameters": {
        "symbol": "ETH"
    }
}

Using the service directly:

service = CryptoService()
result = await service.call({"symbol": "ETH"})
print(result["price_usd"])  # e.g., 2932.25
await service.cleanup()
Source code in core/services/base.py 
12
13
14
15
16
17
18
19
def __init__(self, http_client: httpx.AsyncClient | None = None):
    """Initialize service.

    Args:
        http_client: Optional HTTP client (will create one if not provided)
    """
    self._http_client = http_client
    self._owns_client = http_client is None

call async 

call(parameters: dict[str, Any] | None = None) -> dict[str, Any]

Get cryptocurrency price data by symbol.

Retrieves comprehensive market data for the specified cryptocurrency symbol from the CoinLore API.

Parameters:

  • parameters (dict[str, Any] | None, default: None ) –

    Optional service parameters dictionary containing:

    • symbol (str, optional): Cryptocurrency symbol to query (e.g., "BTC", "ETH", "SOL", "DOGE"). Case-insensitive. Defaults to "BTC" if not provided.

Returns:

  • dict[str, Any] –

    Dictionary containing cryptocurrency market data with the following structure:

  • dict[str, Any] –

    ```python

  • dict[str, Any] –

    { "symbol": str, # e.g., "BTC" "name": str, # e.g., "Bitcoin" "rank": int, # Market cap rank "price_usd": float, # Price in USD "percent_change_24h": float, # 24h change % "percent_change_1h": float, # 1h change % "percent_change_7d": float, # 7d change % "market_cap_usd": float, # Market cap in USD "volume24": float, # 24h volume "price_btc": float, # Price in BTC "csupply": str, # Circulating supply "tsupply": str, # Total supply "msupply": str # Max supply (may be None)

  • dict[str, Any] –

    }

  • dict[str, Any] –

    ```

Raises:

  • ValidationError –

    If the API request fails or the symbol is not found.

Examples:

service = CryptoService()
result = await service.call({"symbol": "ETH"})
print(result["price_usd"])  # e.g., 2932.25
await service.cleanup()
Source code in services/crypto_service.py 
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
async def call(self, parameters: dict[str, Any] | None = None) -> dict[str, Any]:
    """Get cryptocurrency price data by symbol.

    Retrieves comprehensive market data for the specified cryptocurrency
    symbol from the CoinLore API.

    Args:
        parameters: Optional service parameters dictionary containing:

            - symbol (str, optional): Cryptocurrency symbol to query
              (e.g., "BTC", "ETH", "SOL", "DOGE"). Case-insensitive.
              Defaults to "BTC" if not provided.

    Returns:
        Dictionary containing cryptocurrency market data with the following structure:

        ```python
        {
            "symbol": str,              # e.g., "BTC"
            "name": str,                 # e.g., "Bitcoin"
            "rank": int,                 # Market cap rank
            "price_usd": float,          # Price in USD
            "percent_change_24h": float, # 24h change %
            "percent_change_1h": float,  # 1h change %
            "percent_change_7d": float,  # 7d change %
            "market_cap_usd": float,     # Market cap in USD
            "volume24": float,          # 24h volume
            "price_btc": float,         # Price in BTC
            "csupply": str,              # Circulating supply
            "tsupply": str,              # Total supply
            "msupply": str               # Max supply (may be None)
        }
        ```

    Raises:
        ValidationError: If the API request fails or the symbol is not found.

    Examples:
        ```python
        service = CryptoService()
        result = await service.call({"symbol": "ETH"})
        print(result["price_usd"])  # e.g., 2932.25
        await service.cleanup()
        ```
    """
    # Extract symbol from parameters, defaulting to "BTC"
    symbol = "BTC"
    if parameters and "symbol" in parameters:
        symbol = str(parameters["symbol"]).strip()
        if not symbol:
            symbol = "BTC"  # Fallback to BTC if empty string provided

    # Get HTTP client from base class
    client = await self.get_http_client()

    # Fetch and return cryptocurrency data
    return await get_price_data(symbol=symbol, client=client)

Creating Custom Services

See the Creating Services Guide for detailed information on creating your own services.

Quick example:

from core.services.base import BaseService

class MyService(BaseService):
    """My custom service."""

    async def call(self, parameters: dict | None = None) -> dict:
        """Process the service request.

        Args:
            parameters: Optional parameters for the service

        Returns:
            Service response data
        """
        return {"result": "data"}

Next Steps