Create API functions

Here are two examples of API functions:

weather service
authentication system

To select an example, click either the Weather API or Authentication filter at the top of the page.

Before you begin

To use this example, generate a free API key from weatherapi.com.

Import required types

Import the necessary types from the Redocly configuration. These types provide TypeScript definitions for the request and context objects.

Define the main function

Define the main API function that handles the request. The function takes two parameters:

Add custom authentication (optional)

Handle query parameters

Extract and validate query parameters from the request. The weather API requires a location parameter (q).

Access environment variables

Access the API key from environment variables using process.env. Environment variables are a secure way to store sensitive information like API keys.

Make the API request

Make a call to the external weather API using fetch API, and validate the response.

Return formatted response

Format and return the weather data in a structured JSON response.

Handle errors

Implement error handling for API requests to manage failures and provide useful error messages to clients.

Reference documentation

To learn more about API functions, see the API functions reference for available helper methods and properties.

import type { ApiFunctionsContext } from '@redocly/config';

export default async function (
  request: Request, 
  context: ApiFunctionsContext
) {

  // Get query parameters
  const { q } = context.query;
  
  if (!q) {
    return context.status(400).json({ 
      error: 'Missing location parameter', 
      message: 'Please provide a location using the q parameter' 
    });
  }

  try {
    // Get the API key from environment variables
    const apiKey = process.env.WEATHER_API_KEY;
    
    if (!apiKey) {
      return context.status(500).json({ 
        error: 'Server configuration error', 
        message: 'Weather API key is not configured' 
      });
    }

    // Call the external weather API
    const weatherResponse = await fetch(
      `https://api.weatherapi.com/v1/current.json?key=${apiKey}&q=${encodeURIComponent(q)}&aqi=no`
    );
    
    if (!weatherResponse.ok) {
      const errorData = await weatherResponse.json();
      return context.status(weatherResponse.status).json({
        error: 'Weather API error',
        message: errorData.error?.message || 'Failed to fetch weather data',
        code: errorData.error?.code
      });
    }

    const weatherData = await weatherResponse.json();
    
    // Return formatted weather data
    return context.status(200).json({
      location: {
        name: weatherData.location.name,
        region: weatherData.location.region,
        country: weatherData.location.country,
        lat: weatherData.location.lat,
        lon: weatherData.location.lon,
        localtime: weatherData.location.localtime
      },
      current: {
        temp_c: weatherData.current.temp_c,
        temp_f: weatherData.current.temp_f,
        condition: weatherData.current.condition,
        wind_kph: weatherData.current.wind_kph,
        wind_mph: weatherData.current.wind_mph,
        humidity: weatherData.current.humidity,
        feelslike_c: weatherData.current.feelslike_c,
        feelslike_f: weatherData.current.feelslike_f
      }
    });
  } catch (error) {
    return context.status(500).json({ error: 'Internal server error' });
  }
}