Pairings

Introduction

This API route allows you to generate beverage pairings that go well with a given meal. It provides two endpoints, each with a different response format:

• JSON Route: Returns the pairings details as JSON.
• Readable Stream Route: Streams the pairings details in a readable stream.

Authentication

To access these endpoints, you must include an Authorization header with a valid API key.

Common Request Parameters

Both routes accept the following request parameters:

• drinkType (enum, required): Specifies the type of beverage you want recommendations for ['beer', 'wine']
• meal (string, required): Describes the meal for which you want beverage pairings.

JSON Route Details

Endpoint

POST /api/generate/pairings

Request Example

POST /api/generate/pairings
Headers:
{
  "Authorization": "YOUR_API_KEY"
}
Body:
{
  "drinkType": "wine",
  "meal": "Grilled Salmon"
}

Response (JSON)

• Status Code: 200 (OK)
• Content-Type: application/json

[
  {
    "rank": 1,
    "producer": "Winery A",
    "name": "Wine 1",
    "styles": "Red",
    "country": "US",
    "tasteProfile": {
      "sweetness": "Dry",
      "acidity": "Medium",
      "tannin": "High",
      "body": "Full"
    },
    "alcolVolume": "13%",
    "priceRange": "$$$"
  },
  // Additional pairings...
]

Readable Stream Route Details

Endpoint

POST /api/generate/stream/pairings

Request Example

POST /api/generate/stream/pairings
Headers:
{
  "Authorization": "YOUR_API_KEY"
}
Body:
{
  "drinkType": "wine",
  "meal": "Grilled Salmon"
}

Response (Readable Stream)

• Status Code: 200 (OK)
• Content-Type: application/json (Streaming)

[
  {
    "rank": 1,
    "producer": "Winery A",
    "name": "Wine 1",
    "styles": "Red",
    "country": "US",
    "tasteProfile": {
      "sweetness": "Dry",
      "acidity": "Medium",
      "tannin": "High",
      "body": "Full"
    },
    "alcolVolume": "13%",
    "priceRange": "$$$"
  },
  // Additional pairings...
]

The response is streamed and varies in size based on the generated content. On the client side, you should process the stream accordingly.

Handling the Readable Stream Response (JavaScript Example)

To handle the Readable Stream response in JavaScript, you can use the following code as an example:

const responseStream = fetch('/api/generate/stream/pairings', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "drinkType": "wine",
  "meal": "Grilled Salmon"
}
),
});

// Process the stream
responseStream.then(async (response) => {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (!done) {
      const { value, done: doneReading } = await reader.read();

      done = doneReading; // Break the loop if stream completed
      const newValue = decoder.decode(value);
      chunks = chunks + newValue;
    }

    // Parses the completed response (pairings data)
    const pairingsData = JSON.parse(chunks);

    // Handle the pairings data as needed
    console.log(pairingsData);

});

Execution Time

As responses are generated on the fly through AI, response time will vary depending on the lenght of the response. Approximate time for response is 15s for the 'pairings' endpoint.

Error Responses

Both routes return specific error responses for various scenarios:

• Missing API Key (Status Code: 403):
  • Response: No API Key in request
• Invalid API Key (Status Code: 403):
  • Response: Invalid API Key
• Missing Required Inputs (Status Code: 400):
  • Response: Required inputs not provided
• Inactive Subscription (Status Code: 403):
  • Response: You don't have an active subscription