OpenEmbed

This is a placeholder for a diagram. Do not edit this line directly.

OpenEmbed is a service that allows your blocklet and its components to expose oEmbed-compatible endpoints. This makes it possible for other websites and applications to easily discover and embed content from your blocklet, enhancing its discoverability and integration capabilities. The service aggregates OpenEmbed data from all running components and provides it in both JSON and YAML formats.

This guide explains how the OpenEmbed service works and how you, as a developer, can make your blocklet's components compatible with it.

How It Works

The OpenEmbed service operates on a discovery and aggregation model. When an external application (a consumer) wants to embed content from your blocklet, it first needs to discover the available embeddable resources. Blocklet Service facilitates this by providing a standardized endpoint.

The process is as follows:

1. Discovery

   An oEmbed consumer queries the well-known endpoint provided by the Blocklet Service: /.well-known/openembed.json.

2. Internal Query

   The Blocklet Service, upon receiving the request, scans for all active child components that are configured to provide OpenEmbed data.

3. Data Fetching

   For each compatible component, the service makes an internal request to a specific path within that component (/__blocklet__/openembed.json) to retrieve its list of embeddable content URLs.

4. Aggregation & Enrichment

   The service collects the responses from all components. It enriches this data by prefixing each embeddable path with its component's mount point and adding relevant metadata.

5. Response

   The service returns a single, aggregated openembed.json (or .yaml) file to the consumer, containing a complete list of all embeddable content from the entire blocklet application.

The following diagram illustrates this data flow: This is a placeholder for a diagram. Do not edit this line directly.

Developer Implementation

To make a component's content embeddable, you must expose a JSON endpoint that provides metadata about the resources you want to make available.

1. Create the OpenEmbed Endpoint

Within your component, create a route that responds to GET requests at /__blocklet__/openembed.json. This is the fixed path that the Blocklet Service will query.

The response from this endpoint must include the x-blocklet-openembed: true header to be recognized by the service.

2. Define the JSON Structure

The JSON file served by your endpoint should define the embeddable paths and their properties. The core of this file is the embeds object, where each key is a URL path (relative to the component's root) and the value is an object describing the resource, following the oEmbed specification.

Here is an example of what a component's openembed.json file might look like:

component/openembed.json

{
  "info": {
    "version": "1.2.0"
  },
  "embeds": {
    "/posts/{post-id}": {
      "get": {
        "summary": "Embed a single blog post",
        "description": "Provides an oEmbed-compatible response for a single blog post, allowing it to be embedded in external sites.",
        "parameters": [
          {
            "name": "post-id",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the post to embed.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "oEmbed Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string", "example": "rich" },
                    "version": { "type": "string", "example": "1.0" },
                    "title": { "type": "string" },
                    "author_name": { "type": "string" },
                    "provider_name": { "type": "string" },
                    "html": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Service API Endpoints

The Blocklet Service exposes the following public endpoints for consumers to discover embeddable content.

Get Aggregated OpenEmbed Data

Data Structures

The final output from the service endpoint is a merged and enriched version of the data provided by the individual components.

Top-Level Object

Embed Item Object

Each key within the main embeds object is a full URL path (e.g., /my-component/posts/{post-id}), and its value is an object with the following structure.