Recipe Tour Builder API

The Recipe Tour Builder API provides comprehensive functionality for creating, managing, and exporting guided onboarding tours for Drupal recipes. This API enables recipe developers to build interactive step-by-step tours that guide users through recipe installation and configuration.

Quick Start

Prerequisites

Drupal 10.3+ or 11.x
tour module enabled
recipe_onboarding module enabled
recipe_onboarding_tour_builder submodule enabled
Appropriate permissions assigned

Basic Usage

Create a tour:

curl -X POST /admin/structure/recipe-onboarding/tours \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My First Tour",
    "recipe_id": "blog_setup",
    "creation_method": "visual"
  }'

Add tour steps (via AJAX):

fetch('/api/recipe-tour-builder/tour/my_tour/step', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    stepId: 'new-step',
    stepData: {
      title: 'Welcome',
      body: 'Welcome to this tour!',
      selector: '.toolbar-bar',
      location: 'bottom'
    }
  })
})

Export as recipe:

curl -X POST /admin/structure/recipe-onboarding/tours/my_tour/export \
  -H "Content-Type: application/json" \
  -d '{
    "action": "export_only",
    "recipe_name": "My Recipe",
    "export_format": "zip"
  }'

OpenAPI Specification

The complete OpenAPI 3.0 specification is available at:

Standalone: recipe-tour-builder-api.yaml
Integrated: openapi-complete-specification.yaml (includes all LLM Platform APIs)

Core Concepts

Tours

A Tour is the main entity representing a guided walkthrough. Each tour:

Has a unique machine name (ID)
Contains multiple steps (tips)
Can be linked to a recipe entity
Supports templates for quick creation
Can be exported as installable Drupal recipes

{
  "id": "recipe_blog_setup_1234567890",
  "label": "Blog Setup Tour",
  "status": true,
  "routes": [
    {"route_name": "system.admin_content"}
  ],
  "tips": [
    {
      "id": "welcome_step",
      "label": "Welcome",
      "body": "Welcome to the blog setup!",
      "selector": ".toolbar-bar",
      "location": "bottom",
      "weight": 0
    }
  ],
  "recipe_id": "blog_setup_recipe"
}

Tour Steps (Tips)

Each Tour Step represents a single point in the guided experience:

ID: Unique step identifier
Label: Step title shown to users
Body: Step content/instructions
Selector: CSS selector for target element
Location: Position relative to target (top, bottom, left, right, center)
Weight: Display order

Templates

Templates provide pre-built tour structures for common scenarios:

Basic: Simple welcome → completion flow
Content Creation: Guide through content management
Site Building: Structure and configuration walkthrough
Configuration: System settings tour

Recipe Export

Tours can be exported as Drupal Recipes with three options:

Update Existing: Update linked recipe entity
Create New: Create new recipe entity + export
Export Only: Generate recipe files without entity

API Endpoints

Core Management

Method	Endpoint	Description
`GET`	`/admin/structure/recipe-onboarding/tours`	List all tours
`POST`	`/admin/structure/recipe-onboarding/tours`	Create new tour
`GET`	`/admin/structure/recipe-onboarding/tours/{tour}`	Get tour details
`PUT`	`/admin/structure/recipe-onboarding/tours/{tour}`	Update tour
`DELETE`	`/admin/structure/recipe-onboarding/tours/{tour}`	Delete tour

Visual Builder

Method	Endpoint	Description
`GET`	`/admin/structure/recipe-onboarding/tours/{tour}/builder`	Visual builder UI
`POST`	`/api/recipe-tour-builder/tour/{tour}/step`	Save step (AJAX)
`DELETE`	`/api/recipe-tour-builder/tour/{tour}/step/{step_id}`	Delete step (AJAX)
`POST`	`/api/recipe-tour-builder/tour/{tour}/reorder`	Reorder steps (AJAX)

Templates

Method	Endpoint	Description
`GET`	`/admin/structure/recipe-onboarding/tours/templates`	List templates
`GET`	`/admin/structure/recipe-onboarding/tours/templates/{template}`	Get template

Export & Preview

Method	Endpoint	Description
`GET`	`/admin/structure/recipe-onboarding/tours/{tour}/export`	Export form
`POST`	`/admin/structure/recipe-onboarding/tours/{tour}/export`	Export tour
`GET`	`/admin/structure/recipe-onboarding/tours/{tour}/preview`	Preview tour

Analytics

Method	Endpoint	Description
`GET`	`/admin/structure/recipe-onboarding/tours/{tour}/analytics`	Tour analytics

Authentication & Permissions

Authentication Methods

Drupal Session (web interface):
```
Cookie: SESS=your_drupal_session_id
```

JWT Bearer Token (API access):

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

API Key (service-to-service):
```
X-API-Key: your_api_key_here
```

Required Permissions

create recipe tours: Create new tours
edit recipe tours: Modify existing tours
delete recipe tours: Remove tours
export recipe tours: Export tours as recipes
view recipe tour analytics: Access usage statistics
administer recipe tours: Full administrative access

Integration Examples

JavaScript Integration

class TourBuilder {
  constructor(tourId) {
    this.tourId = tourId;
    this.apiBase = '/api/recipe-tour-builder';
  }

  async addStep(stepData) {
    const response = await fetch(`${this.apiBase}/tour/${this.tourId}/step`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Requested-With': 'XMLHttpRequest'
      },
      body: JSON.stringify({
        stepId: 'new-step',
        stepData: stepData
      })
    });
    
    return response.json();
  }

  async reorderSteps(stepOrder) {
    const response = await fetch(`${this.apiBase}/tour/${this.tourId}/reorder`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Requested-With': 'XMLHttpRequest'
      },
      body: JSON.stringify({ order: stepOrder })
    });
    
    return response.json();
  }
}

// Usage
const builder = new TourBuilder('my_tour_id');
await builder.addStep({
  title: 'New Step',
  body: 'Step content here',
  selector: '.my-element',
  location: 'top'
});

PHP Integration

<?php

use Drupal\recipe_onboarding_tour_builder\Service\TourBuilderService;
use Drupal\recipe_onboarding_tour_builder\Service\RecipeExportService;

// Get services
$tourBuilder = \Drupal::service('recipe_onboarding_tour_builder.builder');
$recipeExport = \Drupal::service('recipe_onboarding_tour_builder.recipe_export');

// Create a tour
$tour = $tourBuilder->createTour('my_recipe', [
  'label' => 'My Custom Tour',
  'routes' => [['route_name' => 'system.admin_content']],
  'enable_analytics' => TRUE,
]);

// Add steps
$tourBuilder->addStep($tour, [
  'label' => 'Welcome',
  'body' => 'Welcome to this tour!',
  'selector' => '.toolbar-bar',
  'location' => 'bottom',
]);

// Export as recipe
$recipePath = $recipeExport->exportTourAsRecipe($tour, [
  'name' => 'My Exported Recipe',
  'include_readme' => TRUE,
]);

Drush Integration

# Enable the module
drush en recipe_onboarding_tour_builder -y

# Clear cache
drush cr

# Check module status
drush pm:list | grep recipe_onboarding

# Export configuration
drush config:export

Error Handling

Common Error Responses

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "label",
      "message": "Tour name is required",
      "code": "required"
    }
  ]
}

HTTP Status Codes

200: Success
201: Created
400: Bad Request (validation errors)
403: Forbidden (insufficient permissions)
404: Not Found
422: Unprocessable Entity
500: Internal Server Error

Testing

Playwright E2E Tests

The module includes comprehensive Playwright tests:

cd modules/recipe_onboarding_tour_builder
npm install
npx playwright install
npm test

Test Categories

Tour Management: CRUD operations
Visual Builder: Drag-and-drop functionality
Recipe Export: Export workflows
Analytics: Usage tracking
Accessibility: WCAG compliance
Performance: Load times and responsiveness

Rate Limiting

API endpoints are subject to Drupal's standard rate limiting:

Authenticated requests: 100/minute per user
Anonymous requests: 20/minute per IP
AJAX requests: 200/minute per session

Changelog

Version 1.0.0

Initial release
Visual tour builder
Template system
Recipe export functionality
Analytics tracking
Playwright test suite
OpenAPI 3.0 specification

Support & Contributing

Issues: GitLab Issues
Documentation: Development Guide
Contributing: Getting Started Guide

Quick Start​

Prerequisites​

Basic Usage​

OpenAPI Specification​

Core Concepts​

Tours​

Tour Steps (Tips)​

Templates​

Recipe Export​

API Endpoints​

Core Management​

Visual Builder​

Templates​

Export & Preview​

Analytics​

Authentication & Permissions​

Authentication Methods​

Required Permissions​

Integration Examples​

JavaScript Integration​

PHP Integration​

Drush Integration​

Error Handling​

Common Error Responses​

HTTP Status Codes​

Testing​

Playwright E2E Tests​

Test Categories​

Rate Limiting​

Changelog​

Version 1.0.0​

Support & Contributing​

Related APIs​

Quick Start

Prerequisites

Basic Usage

OpenAPI Specification

Core Concepts

Tours

Tour Steps (Tips)

Templates

Recipe Export

API Endpoints

Core Management

Visual Builder

Templates

Export & Preview

Analytics

Authentication & Permissions

Authentication Methods

Required Permissions

Integration Examples

JavaScript Integration

PHP Integration

Drush Integration

Error Handling

Common Error Responses

HTTP Status Codes

Testing

Playwright E2E Tests

Test Categories

Rate Limiting

Changelog

Version 1.0.0

Support & Contributing

Related APIs