SONIC API Manual

Welcome to SONIC API, a simple and efficient API service that returns an album cover image for a given artist. This service normalizes the artist's name, removes unnecessary words like "the", and fetches the album cover based on a predefined mapping of artist names to cover images.

Overview

• Fetch an album cover image for a given artist.
• Use the API with or without an API key depending on your environment.
• Retrieve a default "not found" image when an artist's cover is not available.

How It Works

1. The API normalizes the artist name to avoid variations (e.g., capitalization, special characters).
2. It searches for the artist in a JSON-based artist-cover mapping file (`/public/artist-covers.json`).
3. If the artist is found, it returns the corresponding `.webp` image from the `/public/covers` folder.
4. If not found, it returns a default "not-found.webp" image.

Getting Started

Installation

1. Clone the repository:

git clone https://github.com/ncradio-fm/sonic-api

2. Set up your environment variables. Create a .env.local file using the provided env-example:

cp env-example .env.local

3. Update .env.local with your configuration:

API_KEY=your-api-key-here

Running the Application

To start the development server, run:

npm run dev

This will run the server in development mode. The API will be available at http://localhost:3000.

API Request

Endpoint:

GET /api/album-cover?artist=<artist-name>

Headers

• In production mode, you must provide the x-api-key header with the correct API key.

Example Requests

Request:

GET http://localhost:3000/api/album-cover?artist=The%20Beatles

Response:

• If The Beatles exists in the JSON file, returns the album cover as a .webp image.
• If The Beatles does not exist in the JSON file, returns the default "not found" image.

Error Handling

• 400 Bad Request: Returned if the artist parameter is not provided.
• 401 Unauthorized: Returned if the API key is missing or incorrect (in production mode).
• 500 Internal Server Error: Returned if there is an error processing the request.

Environment Variables

• API_KEY: The API key to protect your API in production.

API Usage Example (Production)

To call the API in production, you need to include the x-api-key header with your request. Below is an example using curl:

curl -H "x-api-key: your-api-key-here" "https://your-production-url/api/album-cover?artist=The%20Beatles"

This will send a GET request to the API to fetch the album cover for the artist The Beatles, with the API key provided in the headers.

Ensure that you replace your-api-key-here with the actual API key and your-production-url with the correct production URL of your API.

Author

Made by NikitaY.
(C) 01-Sep-2024, nikitay.com