iamcal / oembed Goto Github PK

View Code? Open in Web Editor NEW

1.3K 58.0 633.0 3.77 MB

The oEmbed Spec

Home Page: http://oembed.com

License: MIT License

HTML 11.23% PHP 85.18% Shell 2.03% JavaScript 1.56%

oembed's Introduction

oEmbed Spec

This repo represents the current oEmbed spec as seen at http://oembed.com and any drafts, in the www directory.

It also contains configuration information (the registry) for oEmbed providers, as YAML files in the providers directory.

Consuming the provider registry

If you need to use the provider registry directly, you can install this package using NPM:

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

That will install the providers file into node_modules/oembed-providers/providers.json, where you can ingest it directly.

Maintainers: Publishing to NPM

Update version in package.json to today's date
npm login if you haven't already
npm publish
Check https://www.npmjs.com/package/oembed-providers

oembed's People

Stargazers

Watchers

Forkers

adewale embedly jaipandya schuyler1d foolswis bdougherty mchung cloudappsetup 23d jklfa starfishmod barryhunter compumike fingertrick comewalk tregoning hotboyksa jpages38 msroot igorgladkoborodov mpettitt djajalla c2webdev landsurveyorsunited tusharrex sloanesturz atttune emkay meti663 itteco pierreant-p asinsalasilva accusoft aeminem pyembed robbygenius kharri1073 marcsallent destock forumrunner yenyichiang nathanjones clyp vincehu xuanvu ryanthecubfan rafaelmartins martynasma agiza bryceageno nacyot rb-cohen bharatpatil mtwentyman etro2148 anandselva jphillips-gettyimages everyplace fredericcambon torbjon liluxdev nowpc2 mathildes demsec gitmh fadizahhar bangpound itswarmaster aaronjorbin pento pedrolec01 nitroy2k ob1y2k rshubbard nooyoo11 matt-thomson yoonited hoangpnr marig345 ck-romeo makelivedotnet kanenas ambrugeat hannes-marais romainneutron patou meteormag bergmark jpadilla skavish animatron waabeh boldewyn rub3nlh wassy24 stelabouras ariefwt buitrungnghia15031993 itsalif devongovett

oembed's Issues

Discontinued

Hi!
Is this project discontinued or something?

Are someone here to help?

Thanks!

add linter for YAML

if i add a travis test, i can avoid merging broken YAML at least

http://oembed.com/ - not working examples

Animoto (http://animoto.com/)

URL scheme: http://animoto.com/play/*
API endpoint: http://animoto.com/oembeds/create 
Notice: Undefined index: formats in /var/www/html/oembed.com/index.php on line 465
Documentation: http://help.animoto.com/entries/109992-oEmbed-API
Example: http://animoto.com/oembeds/create/?format=xml&url=http%3A%2F%2Fanimoto.com%2Fplay%2FJzwsBn5FRVxS0qoqcBP5zA

Notice: Undefined index: notes in /var/www/html/oembed.com/index.php on line 479

Notice: Undefined index: discovery in /var/www/html/oembed.com/index.php on line 483

All examples display like this:

Notice: Undefined index: notes in /var/www/html/oembed.com/index.php on line 479
Notice: Undefined index: discovery in /var/www/html/oembed.com/index.php on line 483

Youtube Video

Hello,
I try to embed a youtube video and I get this response:

SyntaxError: Unexpected token ':'

I'm currently use jquery 1.7 (latest version) with oembed downloaded form google code (http://code.google.com/p/jquery-oembed/)

I have tryed to update the plugin with this code: http://stackoverflow.com/questions/4928926/using-own-handler-for-jquery-oembed but I get the same error.

Thanks

Suggest oembed endpoint support embed url modifiers

Services such as Youtube do not respond to URL options that their front end embed form creates.

For Youtube, on any video in the front-end, the embed creator under their 'share' option allows you to turn off suggested videos and turn off controls. This is internally done by appending the options 'rel=0' and 'controls=1' to the URL in the iframe src url.. However, adding these options to the oembed request will not result in them being in the returned URL output. In order for the options to work, they have to be regex'd back in after the response.

I think it would be very beneficial to strongly suggest that any modifiers a service has for their embeds should be available through oembed. This way, anything available in the front-end would be reasonably available in the oembed endpoint, too.

Missing types

Nothing explicitly enforces to return version as a string or number ("version":1.0 seems as valid as "version":"1.0").

In the same way cache_age can be a string or a number.

introduce oembed logo

Similar to HTML5 logo and CSS3 logo:

Support for different language in title and description

Hi,
Does oEmbed suppport multiple language? In youtube from some time videos can have translated titles.
oEmbed always returning default language and as far as I see in specs it doesn't support titles and description. Is that true?

Allow for static sites to be discoverable without a true endpoint

I was thinking about how a static site might support oEmbed, and, it seems impossible currently if complying to the full spec.

I was thinking the spec could be changed so that it might be possible for such sites to be discoverable, with static json and xml files, without a true endpoint.

E.g., imagine a blog hosted at http://example.com/ that is built with Jekyl. A single blog post might be at http://example.com/2015/10/my-post.html. Within the <head> for that page, would be <link> tags for oEmbed discovery, which might say:

<link rel="alternate" type="application/json+oembed"
  href="http://example.com/oembed/2015/10/my-post.json" title="My Post oEmbed Profile" />
<link rel="alternate" type="text/xml+oembed"
  href="http://example.com/oembed/2015/10/my-post.xml" title="My Post oEmbed Profile" />

However, there would be no true endpoint. You couldn't, e.g., GET http://example.com/oembed?url=http%3A%2F%2Fexample.com%2F2015%2F10%2Fmy-post.html&format=json.

This would provide a lower barrier for small sites to support their own oEmbed.

Providers must specify one or more URL scheme and API endpoint pairs

From what I understand this means that all providers must specify these, yet for YouTube (and some others) I don't see any scheme url's. Am I missing something here or is the http://oembed.com/providers.json simply incomplete?

Entry for Twitch does not contain http or https

The current entry for Twitch looks like this:

{
        "provider_name": "Twitch",
        "provider_url": "\/\/www.twitch.tv",
        "endpoints": [
            {
                "schemes": [
                    "\/\/clips.twitch.tv\/*",
                    "\/\/www.twitch.tv\/*",
                    "\/\/twitch.tv\/*"
                ],
                "url": "\/\/api.twitch.tv\/v4\/oembed",
                "formats": [
                    "json"
                ]
            }
        ]
    },

Are providers required to have "http:" or "https:" as a prefix for their "provider_url" and "scheme" entries?

No place to report security issues

I dare not post them here...

List of providers in some programatically format

Hello,

while I really like the oEmbed spec, I miss a centralized list of providers I can rely on. Auto discovering providers is pretty cool, but not all the providers are allowing it, and it is quite hard for webapps that rely heavily on ajax, like rdio.com.

I did some effort on getting such list in JSON scrapping oembed.com, but several providers seems to be outdated or with wrong schemes:

https://github.com/rafaelmartins/oembed-providers

what about adding a list like this one to oembed.com, even if manually maintained, so people who adds new providers can fix the list too, and keep it up2date?

Added Jest.com to Provider section of Spec

Added Jest.com oembed information here:

https://github.com/zinktic/oembed/commit/a635937ce76d0a1e37905fea0ab245f1df9aa4bc

Please update.
Thanks,
Sanket

Youtube stopped working

I installed the oEmbed option on a clients website recently so they could embed Youtube and Vimeo videos in a video gallery using the URL only. I really like the whole principle behind oEmbed and how it made it all rather simple.

All worked fine during the development phase, both youtube and vimeo videos were displaying as expected and everyone was happy with the results and we were looking to go live with the gallery this week.

This morning however it looks like the Youtube videos are no longer embedding as they were previously. The vimeo videos are still functioning fine it is just the youtube ones that seem to be broken.

you can see this example here:

http://www.nzhunter.co.nz/post-your-video-reader-gallery

We haven't changed anything in regards to the oEmbed coding for about 5 days so this came as a complete surprise and has us scratching our heads as to why.

Do you know of any changes that have happened with oEmbed or Youtube that would be causing this to just stop working like it has???

Any help will be appreciated as I've got to the point where it seems likely that something has change outside my control eg. Youtube has changed support for oEmbed or something to that effect

Thanks.

Rick

401 vs. 403

The spec requires that providers respond with 401 Unauthorized to private resources.

The HTTP 1.1 spec, however says:

10.4.2 401 Unauthorized

The request requires user authentication. The response MUST include a WWW-Authenticate header field (section 14.47)
containing a challenge applicable to the requested resource.

401 is only for when the user can authenticate to view the resource, but didn't. Like when you try to access a URL under basic auth and didn't provide username and password.

In the case of private resources, 403 Forbidden should be used, instead of 401 Unauthorized. 403's description depicts our situation very well:

10.4.4 403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

youtube wrong height autodetection

http://www.youtube.com/watch?v=5EayDPIjp40

try to embed this 16:9 video into wordpress or twitter and you see 4:3

i didnt know why youtube differently embed

Why no "audio" type?

Why is there no 'audio' type in the spec?

We only have video, photo, link and rich - which can all return html, be it for an image or an iframe with an HTML5 video player in it or some Flash.

So, seeing as we can easily put HTML5 audio players in iframes, I think that we should be able to define them as such. As 'audio'.

Sure, 'rich' could be a document PDF or something, arbitrary. But why is audio not a 'first class type'?

It's the most easily created and consumed media type in most of the world, yet constantly overlooked (because we can't 'see' it? ;) )

thanks.
Kosso

could you release this year's commits to npm please ?

Thanks !

API endpoint vs. HTTPS

The spec explicitly states that the API endpoint must be on HTTP. However, when embedding content on a site hosted on HTTPS the requests can cause browsers to complain of mixed security content.

Additionally, when a call to the API endpoint is made via HTTPS, the provider should assume that the requester wants the embedded content to be retrieved via HTTPS as well.

Vimeo already appears to behave this way.

"thumbnail width"

It says "thumbnail width" as the identifier name instead of "thumbnail_width".

future spec suggestion: include a (optional) `canonical_url` in the response payload as core attribute

The mailing list seems dead, so I this seems to be the best place for a suggestion / wishlist for future specs (if there is one). I didn't see this covered in the history of either.

It would be nice if the spec encouraged/suggested providers to include the "canonical" url in the payload.

Why?

We consume a fair amount of data via oEmbed, and consume a fair bit of extra traffic caused by multiple discrete URLs that represent a single URL.

For example (and with the understanding that kw args are for internal use and do not affect the oEmbed response), the html versions of these endpoint all declare the same canonical URL of https://example.com/a and have an identical response:

In addition to various business-logic reasons, in order to keep our cache size under control, we need to use the canonical url as the cache key. To achieve that, we must first do an HTTP request for the actual html document to discern the canonical, then oembed fetch it if there is a cache miss.

While an average oEmbed response from upstream providers is around 3k, the full html pages are usually in the 300-800k range. Providing the canonical in the oEmbed payload would allow for HTML retrieval/parsing to be skipped, and shift all interaction to the oEmbed API.

Good examples of this phenomena are YouTube and Instagram. Both properties are built on the concept of sharing links and capitalize on oEmbed integrations, but also have numerous URLs patterns/generators that will point to a given canonical.

Update GIPHY example

Hi Cal,

Thank you for your work on this document.

I would like to propose one change concerning the GIPHY example. As the API endpoint accepts three types of URL:

IMHO it will be better to use the first one in the example than the link to the GIF image itself in the doc like for other providers.

I hope you will consider this change.

Cross platform compatible

Using html in types like video makes it not really compatible with other platforms other than browser. In fact it is a bad format for browser too, it has assumptions about rendering and forces to use iframe to avoid xss.

Cross platform compatible

Providing html in json like in the video type makes the format cross-platform incompatible. Why not to change that?

Add Instagram schemes to support www.

Looking at https://github.com/iamcal/oembed/blob/master/providers/instagram.yml it appears that Instagram schemes are missing support for www.. This may be new, but it appears that Instagram now uses www. for canonical URLs.

ex: https://instagram.com/p/BUHouXdgTWv -> https://www.instagram.com/p/BUHouXdgTWv

This can cause some downstream affects on users copy/pasting urls from Instagram to share links.

Would it be possible to add support for www. here as well?

type:link example does not work

The example for the link type (section 5.2) gives a 404. It seems iamcal.com no longer supports oembed, or at least not with the old url scheme - is that correct?

oEmbed mime types for discovery have unusual "name+type" order

I know I'm late to the party, and this is possibly not easy to change. But RFC 6838 says, that +json and +xml are meant as suffixes. So the correct (according to the IETF) mime types should read

application/oembed+json
text/oembed+xml

How to embed Facebook video in an Android app

Hello,
I am trying to embed a Facebook video into my app and I have tried everything. Short of using an iFrame which looks very ugly I have not found a solution that would show simply the public Facebook video that I want to show my users without me having to direct them to the browser.

Do you have any idea on how I can solve this? I have tried stack overflow, Facebook developer questions and comments and now I am just grasping at straws and would like to know if any of you have ever experienced something like this before?

Two entries for "Codepen". One looks incorrect.

You currently have two entries for "Codepen":
{
"provider_name": "Codepen",
"provider_url": "https://mybeweeg.com",
"endpoints": [
{
"schemes": [
"https://mybeweeg.com/w/"
],
"url": "https://mybeweeg.com/services/oembed"
}
]
},
{
"provider_name": "Codepen",
"provider_url": "https://codepen.io",
"endpoints": [
{
"schemes": [
"http://codepen.io/",
"https://codepen.io/*"
],
"url": "http://codepen.io/api/oembed"
}
]
},

I'm pretty sure the first one is incorrect.

Please Add Library Reference

I wrote this .Net library to make using oEmbed very easy for .Net developers.

http://oembed.codeplex.com/

You can see an example of it in use in this project.

http://www.dotnetnuke.com/Community/Extensions-Forge/view/ProjectDetail/project/dnnmedia.aspx

http://oembed.com/ is offline

http://oembed.com/

Website's down, moving server?

Deep links

Would love if some sort of deep link data was included in the oEmbed spec. This could resemble Twitter Cards or Facebook App Links markup for deep links into apps.

Rdio has been shut down, can be removed from providers

This file here can be removed https://github.com/iamcal/oembed/blob/master/providers/rdio.yml

JSONP handling

Can we make callback part of the spec for jsonp handling? A lot providers already do this to help with client Javascript implementations.

Pownce URL is no longer resolving

http://oembed.com

<p>A <i>consumer</i> (e.g. <a href="http://pownce.com/">Pownce</a>) makes the following HTTP request:</p>

Obviously not a big deal, just thought I would mention it seeing as Pownce closed down almost 6 years ago. :)

Providers must specify one or more URL scheme and API endpoint pairs.

specify WHERE, i wonder

Spec shows illegal end tags

In your example of a YouTube request, you show an example that demonstrates a bug.

There is no such thing as "" or "".

The PARAM end tag is forbidden in HTML4:

http://www.w3.org/TR/html401/struct/objects.html#h-13.3.2

The EMBED tag is an HTML5 construct, and its end tag is also forbidden:
http://dev.w3.org/html5/spec/Overview.html#elements-0
“Void elements only have a start tag; end tags must not be specified for void elements.”

Reported to Google here:

http://code.google.com/p/gdata-issues/issues/detail?id=2346

NY Times incorrect information

The scheme link is wrong. There should be no scheme link.
The url is wrong, it is missing the /{format}/ at the end.

Also related:

The NY Times endpoint fails to honor maxwidth and maxheight.

license ?

Hi,

could you add a LICENSE file to be clearer about how providers list can be distributed ?
Without one, the list is protected by default copyright laws, which are quite restrictive.

"Quick Example" refers to defunct website

It appears that Pownce has been unavailable for five and a half years. A newer consumer might make for a better example.

Provider entry doesn't comply with schema

First provider in providers list Gfycat doesn't comply with schema ('endpoints' field):

    {
        "provider_name": "Gfycat",
        "provider_url": "https:\/\/gfycat.com\/",
        "endpoints": [
            {
                "schemes": [
                    "http:\/\/gfycat.com\/*",
                    "http:\/\/www.gfycat.com\/*",
                    "https:\/\/gfycat.com\/*",
                    "https:\/\/www.hgfycat.com\/*"
                ]
            },
            {
                "url": "https:\/\/api.gfycat.com\/v1\/oembed",
                "discovery": true
            }
        ]
    }

It should be:

    {
        "provider_name": "Gfycat",
        "provider_url": "https:\/\/gfycat.com\/",
        "endpoints": [
            {
                "schemes": [
                    "http:\/\/gfycat.com\/*",
                    "http:\/\/www.gfycat.com\/*",
                    "https:\/\/gfycat.com\/*",
                    "https:\/\/www.hgfycat.com\/*"
                ],
                "url": "https:\/\/api.gfycat.com\/v1\/oembed",
                "discovery": true
            }
        ]
    }

oEmbed service discovery for non-HTML docs?

With reference to https://oembed.com/ section 4 (Service Discovery), it seems that the recommended means of allowing clients to discover an oEmbed service is via some <link> tags in a document body.

Is there a standardised or recommended means for clients to discover oEmbed services for non-HTML data, and/or without having to download and parse the HTML itself? For example, an HTTP header served with the document, something like this:

OEmbed-Provider: https://reference/to/my/oembed/service?url=http://url/to/my/document

... or some other mechanism?

Responsive embeds

Is there any way to request/respond with a size-responsive embed? Is it something that will be added to the standard in the future?

Problem with simple links and image links

Hi,
When i put another link on the $content i don’t get them on the result ! like for images link, http://www.google.com for example and others …

Can you give a fix for this ?

And how i can embed this function to your code ?

function media($str) {
$str = preg_replace_callback('#(?:https?://\S+)|(?:www.\S+)|(?:\S+.\S+)#', function($arr)
{
if(strpos($arr[0], 'http://') !== 0)
{
$arr[0] = 'http://' . $arr[0];
}
$url = parse_url($arr[0]);

// images
if(preg_match('#.(png|jpg|gif)$#', $url['path']))
{
return '';
}
// youtube
if(in_array($url['host'], array('www.youtube.com', 'youtube.com'))
&& $url['path'] == '/watch'
&& isset($url['query']))
{
parse_str($url['query'], $query);
return sprintf('', $query['v']);
}
//links
return sprintf('%1$s', $arr[0]);
}, $str);
return $str;
}

To get all non embed link a href=””……/a and display images links ?

Thank you in advance.

API endpoint vs. HTTPS

The spec explicitly states that the API endpoint must be on HTTP. However, when embedding content on a site hosted on HTTPS the requests can cause browsers to complain of mixed security content.

Additionally, when a call to the API endpoint is made via HTTPS, the provider should assume that the requester wants the embedded content to be retrieved via HTTPS as well.

Vimeo already appears to behave this way.

Facebook

Would someone kindly please add Facebook(!!) support?
https://developers.facebook.com/docs/plugins/oembed-endpoints

Sorry I'm not too good with forking & coding fixes...

How to ensure the providers are secure?

Hi iamcal,

Is there control on the provider list so that I can be confident that all the providers in the list will not do any bad things in the end point and embed code from the response body?

Can't make it work

Hi!
Could someone explain me why this call is interpreted as a 415?
https://www.app.timefounder.com/oembed?maxwidth=1300&maxheight=1300&radius=100&APIkey=uxgtXmuOAHhNyJB8ge0vGAF5yr5tfjjrxHGr&url=https%3A%2F%2Fwww.app.timefounder.com%2Fprojects%2FmainChartWidget

Thanks!

Single Page Applications

I believe there should be a way for single page applications to dynamically provide their oembed endpoint to the outside world.

For instance, if you are using Angular, Ember, etc, the HTML that a server receives when it requests say, and article: http://singlepageapp.com/articles/this-cool-article - It's just going to be the application layout with static, or meaningless META and LINK tags in the header. You can change those tags dynamically so they render in the user's browser, but that's not going to appear for any sort of scraper or programmatic discovery.

It seems like since the requesting agent already knows the URL that it's trying to get to, you should simply need to include this in your header:

<link rel="alternate" type="application/json+oembed" href="http://singlepageapp.com/api/article/oembed" title="singlepageapp oembed endpoint" />

The spec lays out the parameters, and the requester already knows the URL they want (or they wouldn't have been able to get to the page in the first place) so I'm confused as to why each page needs to include its URL in the provider discovery.