OkiDoki LogoMuseum API
  • Home
  • examples
  • museum-api.html

🏛️ Museum API Documentation

v1.2.1REST API

An imaginary, but delightful Museum API for interacting with museum services and information.

📋 Overview

The Museum API offers a comprehensive set of endpoints to interact with museum services, including:

  • 🕐 Operating Hours - Retrieve museum operational schedules
  • 🎪 Special Events - Manage and discover museum events
  • 🎫 Ticketing - Purchase tickets and generate QR codes
  • 📱 Digital Services - Mobile-friendly ticket management

Base URL: https://redocly.com/_mock/docs/openapi/museum-api

🔐 Authentication

curl -H "Authorization: Basic <credentials>" \
     https://redocly.com/_mock/docs/openapi/museum-api/museum-hours

🎪 Special Events

Discover and manage special events at the museum.

List Special Events

# Get upcoming events
curl -X GET "https://redocly.com/_mock/docs/openapi/museum-api/special-events" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json"

# Filter by date range
curl -X GET "https://redocly.com/_mock/docs/openapi/museum-api/special-events?startDate=2023-10-01&endDate=2023-12-31" \
  -H "Authorization: Basic <credentials>"

const apiUrl = 'https://redocly.com/_mock/docs/openapi/museum-api';

async function getSpecialEvents(startDate, endDate) {
  const params = new URLSearchParams();
  if (startDate) params.append('startDate', startDate);
  if (endDate) params.append('endDate', endDate);

  const response = await fetch(`${apiUrl}/special-events?${params}`, {
    headers: {
      'Authorization': 'Basic ' + btoa('username:password'),
      'Accept': 'application/json'
    }
  });

  return response.json();
}

// Usage
const events = await getSpecialEvents('2023-10-01', '2023-12-31');
console.log('Upcoming events:', events);

import requests
from datetime import datetime

def get_special_events(start_date=None, end_date=None):
    url = "https://redocly.com/_mock/docs/openapi/museum-api/special-events"

    params = {}
    if start_date:
        params['startDate'] = start_date
    if end_date:
        params['endDate'] = end_date

    response = requests.get(
        url,
        params=params,
        auth=('username', 'password'),
        headers={'Accept': 'application/json'}
    )

    return response.json()

# Usage
events = get_special_events('2023-10-01', '2023-12-31')
print(f"Found {len(events)} upcoming events")

Response Example:

[
  {
    "eventId": "f3e0e76e-e4a8-466e-ab9c-ae36c15b8e97",
    "name": "Sasquatch Ballet",
    "location": "Seattle... probably",
    "eventDescription": "They're big, they're hairy, but they're also graceful. Come learn how the biggest feet can have the lightest touch.",
    "dates": ["2023-12-15", "2023-12-22"],
    "price": 40
  },
  {
    "eventId": "3be6453c-03eb-4357-ae5a-984a0e574a54", 
    "name": "Pirate Coding Workshop",
    "location": "Computer Room",
    "eventDescription": "Captain Blackbeard shares his love of the C...language. And possibly Arrrrr (R lang).",
    "dates": ["2023-10-29", "2023-10-30", "2023-10-31"],
    "price": 45
  }
]

Create Special Event

curl -X POST "https://redocly.com/_mock/docs/openapi/museum-api/special-events" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dragon Fossil Discovery Workshop",
    "location": "Paleontology Lab",
    "eventDescription": "Hands-on workshop discovering and analyzing dragon fossils with our expert paleontologists.",
    "dates": ["2024-03-15", "2024-03-22"],
    "price": 35
  }'

async function createSpecialEvent(eventData) {
  const response = await fetch('https://redocly.com/_mock/docs/openapi/museum-api/special-events', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + btoa('username:password'),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(eventData)
  });

  return response.json();
}

// Usage
const newEvent = await createSpecialEvent({
  name: "Dragon Fossil Discovery Workshop",
  location: "Paleontology Lab", 
  eventDescription: "Hands-on workshop discovering and analyzing dragon fossils.",
  dates: ["2024-03-15", "2024-03-22"],
  price: 35
});

def create_special_event(event_data):
    response = requests.post(
        "https://redocly.com/_mock/docs/openapi/museum-api/special-events",
        json=event_data,
        auth=('username', 'password'),
        headers={'Content-Type': 'application/json'}
    )
    return response.json()

# Usage  
new_event = create_special_event({
    "name": "Dragon Fossil Discovery Workshop",
    "location": "Paleontology Lab",
    "eventDescription": "Hands-on workshop discovering and analyzing dragon fossils.",
    "dates": ["2024-03-15", "2024-03-22"], 
    "price": 35
})

🎫 Ticketing System

Purchase tickets for general museum entry or special events.

Buy Museum Tickets

# Buy general admission ticket
curl -X POST "https://redocly.com/_mock/docs/openapi/museum-api/tickets" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketType": "general",
    "ticketDate": "2024-03-20",
    "email": "visitor@example.com"
  }'

Response:

{
  "message": "Museum general entry ticket purchased",
  "ticketId": "382c0820-0530-4f4b-99af-13811ad0f17a",
  "ticketType": "general",
  "ticketDate": "2024-03-20",
  "confirmationCode": "ticket-general-e5e5c6-dce78"
}

# Buy special event ticket
curl -X POST "https://redocly.com/_mock/docs/openapi/museum-api/tickets" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "ticketType": "event",
    "eventId": "3be6453c-03eb-4357-ae5a-984a0e574a54",
    "ticketDate": "2023-10-29",
    "email": "coder@example.com"
  }'

Response:

{
  "message": "Museum special event ticket purchased",
  "ticketId": "b811f723-17b2-44f7-8952-24b03e43d8a9",
  "eventName": "Pirate Coding Workshop",
  "ticketType": "event", 
  "ticketDate": "2023-10-29",
  "confirmationCode": "ticket-event-9c55eg-8v82a"
}

Get Ticket QR Code

Generate a scannable QR code for museum entry:

curl -X GET "https://redocly.com/_mock/docs/openapi/museum-api/tickets/382c0820-0530-4f4b-99af-13811ad0f17a/qr" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: image/png" \
  --output ticket-qr.png

async function getTicketQR(ticketId) {
  const response = await fetch(`https://redocly.com/_mock/docs/openapi/museum-api/tickets/${ticketId}/qr`, {
    headers: {
      'Authorization': 'Basic ' + btoa('username:password'),
      'Accept': 'image/png'
    }
  });

  const blob = await response.blob();
  const imageUrl = URL.createObjectURL(blob);

  // Display in an img element
  document.getElementById('qr-code').src = imageUrl;
}

def download_ticket_qr(ticket_id, filename):
    response = requests.get(
        f"https://redocly.com/_mock/docs/openapi/museum-api/tickets/{ticket_id}/qr",
        auth=('username', 'password'),
        headers={'Accept': 'image/png'}
    )

    with open(filename, 'wb') as f:
        f.write(response.content)

    print(f"QR code saved as {filename}")

# Usage
download_ticket_qr("382c0820-0530-4f4b-99af-13811ad0f17a", "my-ticket.png")

🕐 Museum Operations

Get Museum Hours

Retrieve upcoming museum operating hours with flexible date filtering:

# Get hours for next 10 days
curl -X GET "https://redocly.com/_mock/docs/openapi/museum-api/museum-hours" \
  -H "Authorization: Basic <credentials>"

# Get hours for specific date range
curl -X GET "https://redocly.com/_mock/docs/openapi/museum-api/museum-hours?startDate=2024-03-01&page=1&limit=20" \
  -H "Authorization: Basic <credentials>"

async function getMuseumHours(startDate, page = 1, limit = 10) {
  const params = new URLSearchParams({
    page: page.toString(),
    limit: limit.toString()
  });

  if (startDate) {
    params.append('startDate', startDate);
  }

  const response = await fetch(`https://redocly.com/_mock/docs/openapi/museum-api/museum-hours?${params}`, {
    headers: {
      'Authorization': 'Basic ' + btoa('username:password'),
      'Accept': 'application/json'
    }
  });

  return response.json();
}

// Get this week's hours
const hours = await getMuseumHours('2024-03-01', 1, 7);
console.log('Museum hours:', hours);

def get_museum_hours(start_date=None, page=1, limit=10):
    params = {
        'page': page,
        'limit': limit
    }

    if start_date:
        params['startDate'] = start_date

    response = requests.get(
        "https://redocly.com/_mock/docs/openapi/museum-api/museum-hours",
        params=params,
        auth=('username', 'password'),
        headers={'Accept': 'application/json'}
    )

    return response.json()

# Get next week's hours
from datetime import datetime, timedelta
next_week = (datetime.now() + timedelta(days=7)).strftime('%Y-%m-%d')
hours = get_museum_hours(start_date=next_week, limit=7)

Response Example:

[
  {
    "date": "2023-09-11",
    "timeOpen": "09:00", 
    "timeClose": "18:00"
  },
  {
    "date": "2023-09-12",
    "timeOpen": "09:00",
    "timeClose": "18:00" 
  },
  {
    "date": "2023-09-15",
    "timeOpen": "10:00",
    "timeClose": "16:00"
  }
]

Here are some of the exciting special events you can experience:

📚 API Reference

Operations

GET /museum-hours

Get upcoming museum operating hours with optional date filtering and pagination.

Parameters:

  • startDate (query, optional): Starting date (defaults to today)
  • page (query, optional): Page number (default: 1)
  • limit (query, optional): Results per page (default: 10, max: 30)

Events

POST /special-events

Create a new special event

GET /special-events

List upcoming special events

GET /special-events/{eventId}

Get details about a specific event

PATCH /special-events/{eventId}

Update event details

DELETE /special-events/{eventId}

Cancel/delete an event

Tickets

POST /tickets

Purchase museum tickets (general or event-specific)

GET /tickets/{ticketId}/qr

Generate scannable QR code for ticket

  • QR codes are returned as PNG images perfect for mobile wallets
  • All dates use ISO format (YYYY-MM-DD)

🏗️ Data Models

Special Event Structure

{
  "eventId": "3be6453c-03eb-4357-ae5a-984a0e574a54",
  "name": "Pirate Coding Workshop", 
  "location": "Computer Room",
  "eventDescription": "Captain Blackbeard shares his love of the C...language.",
  "dates": ["2023-10-29", "2023-10-30", "2023-10-31"],
  "price": 45
}

Ticket Structure

{
  "ticketId": "b811f723-17b2-44f7-8952-24b03e43d8a9",
  "ticketType": "event",
  "ticketDate": "2023-10-29", 
  "eventId": "3be6453c-03eb-4357-ae5a-984a0e574a54",
  "confirmationCode": "ticket-event-9c55eg-8v82a",
  "message": "Museum special event ticket purchased"
}

Museum Hours Structure

{
  "date": "2023-09-11",
  "timeOpen": "09:00",
  "timeClose": "18:00"
}

🔄 Webhooks

The Museum API supports webhooks for real-time event notifications:

New Event Published

When a new special event is created or updated, a webhook is triggered:

Endpoint: Your configured webhook URL
Method: POST
Content-Type: application/json

{
  "eventId": "dad4bce8-f5cb-4078-a211-995864315e39",
  "name": "Mermaid Treasure Identification and Analysis",
  "location": "Room Sea-12", 
  "eventDescription": "Join us as we review and classify a rare collection...",
  "dates": ["2023-09-05", "2023-09-08"],
  "price": 30
}

💡 Interactive Examples

Complete Ticket Purchase Flow

// 1. Get available events
const events = await getSpecialEvents();
const pirateWorkshop = events.find(e => e.name.includes('Pirate'));

// 2. Purchase event ticket
const ticket = await fetch('https://redocly.com/_mock/docs/openapi/museum-api/tickets', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('username:password'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ticketType: 'event',
    eventId: pirateWorkshop.eventId,
    ticketDate: pirateWorkshop.dates[0],
    email: 'ahoy@pirate.com'
  })
}).then(r => r.json());

// 3. Generate QR code for entry
const qrResponse = await fetch(`https://redocly.com/_mock/docs/openapi/museum-api/tickets/${ticket.ticketId}/qr`, {
  headers: {
    'Authorization': 'Basic ' + btoa('username:password'),
    'Accept': 'image/png'
  }
});

const qrBlob = await qrResponse.blob();
// Display QR code in your app

// Get today's museum hours
const today = new Date().toISOString().split('T')[0];
const todayHours = await getMuseumHours(today, 1, 1);

if (todayHours.length > 0) {
  const hours = todayHours[0];
  console.log(`Museum is open today from ${hours.timeOpen} to ${hours.timeClose}`);
} else {
  console.log('Museum is closed today');
}

🚀 Getting Started

  1. Get API Access: Contact the museum for API credentials
  2. Choose Your Use Case:
  3. Test in Development: Use the mock server at https://redocly.com/_mock/docs/openapi/museum-api
  4. Implement Error Handling: All endpoints return standard HTTP status codes

Generated from OpenAPI 3.1.0 specification • Last updated: 1.0.40