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:
- Discovery: An oEmbed consumer queries the well-known endpoint provided by the Blocklet Service:
/.well-known/openembed.json. - Internal Query: The Blocklet Service, upon receiving the request, scans for all active child components that are configured to provide OpenEmbed data.
- 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. - 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.
- 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": {See all 19 lines
Service API Endpoints#
The Blocklet Service exposes the following public endpoints for consumers to discover embeddable content.
Get Aggregated OpenEmbed Data#
- Endpoint (JSON):
/.well-known/openembed.json - Endpoint (YAML):
/.well-known/openembed.yaml - Method:
GET - Description: Retrieves the aggregated OpenEmbed metadata for all running and compatible components within the blocklet.
- Query Parameters:
did(optional): If provided, the service will only return the OpenEmbed data for the component with the matching DID.
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.