DOCSEARCHbyAlgolia
Submit Docs

oEmbed Provider Registry

repository·master·Indexed 23 days ago

https://github.com/iamcal/oembed

The official registry of oEmbed providers and a living representation of the oEmbed specification. It provides a collection of provider definitions in YAML format, including provider names, base URLs, and API endpoints. The registry can be installed via NPM as the oembed-providers package (version 1.0.20260604).

Tokens
1K
Snippets
3
Records
5
Agent score
81%

What's inside oembed-providers

  1. Format a provider definition for the registry

    master

    Provider definitions in the oembed-providers registry are written in YAML format. Each entry represents a single service provider and must include the provider's name, its base URL, and a list of endpoints that match specific URL schemes.

    Key fields include:

    • provider_name: The name of the service.
    • provider_url: The base URL of the provider.
    • endpoints:
      • schemes: A list of URL patterns (using glob-style *) that trigger this endpoint.
      • url: The actual oEmbed API endpoint URL.
      • docs_url: A link to the provider's API documentation.
      • example_urls: A list of URLs used for testing the provider's response.
      • discovery: A boolean indicating if the provider supports oEmbed discovery.
      • notes: Optional text for maintainers or users regarding specific limitations (e.g., supported types).
    ---
- provider_name: The Provider
  provider_url: http://www.provider.com
  endpoints:
  - schemes:
    - http://img.provider.com/*
    - http://provider.com/post/*
    url: http://api.provider.com/oembed.json
    docs_url: http://dev.provider.com/api/oembed/
    example_urls:
    - http://api.provider.com/oembed.json?url=http://provider.com/post/f00ba2
    discovery: true
    notes: Provider only supports the 'rich' type
...

  2. Install the oEmbed provider registry

    master

    To use the oEmbed provider registry directly in your project, install the package via NPM. This will place the registry data in node_modules/oembed-providers/providers.json, which you can then ingest into your application.

    npm install https://github.com/iamcal/oembed

  3. Run the oEmbed specification website locally using Docker

    master

    The oEmbed specification website is built with PHP and requires the yaml extension. You can run the site locally using the provided Dockerfile to avoid manual environment setup.

    1. Build the Docker image: docker build -t oembed-site .

    2. Run the container, mounting the current directory to allow live edits to the PHP files: docker run --rm -p 8000:8000 -v "$PWD":/var/www/html oembed-site

    3. Access the site at http://localhost:8000.

    Changes made to www/index.php will be reflected immediately upon refreshing the browser without needing to rebuild the image.

    docker build -t oembed-site .

docker run --rm -p 8000:8000 -v "$PWD":/var/www/html oembed-site

  4. Troubleshoot failed oEmbed endpoints

    master

    In the oEmbed provider registry, an endpoint is marked as Failed when the host is unreachable. This typically means the domain no longer resolves or refuses connections. Common error indicators include:

    • network error (ENOTFOUND): The domain name cannot be resolved.
    • network error (EAI_AGAIN): A temporary DNS failure.
    • ECONNRESET: The connection was forcibly closed by the peer.
    • UND_ERR_CONNECT_TIMEOUT: The connection attempt timed out.
    • ERR_SSL_TLSV1_UNRECOGNIZED_NAME or ERR_TLS_CERT_ALTNAME_INVALID: SSL/TLS handshake failures.
    • CERT_HAS_EXPIRED: The endpoint's SSL certificate is no longer valid.

  5. Troubleshoot unverified oEmbed endpoints

    master

    An endpoint is marked as Unverified if it responds to requests but has not returned a valid oEmbed document during testing. This status does not trigger an automatic removal from the registry.

    Common causes for an unverified status include:

    • Stale examples: The provided example URL is no longer valid.
    • WAF/Cloudflare blocks: The provider is blocking the audit request.
    • Dead services: The service returns a 200 OK status page (like a landing page) instead of a valid oEmbed JSON/XML response.

    Resolution: To verify an unverified provider, a fresh example URL must be provided or a manual call must be performed.