iframely/docs/LINKS.md
# Links in Iframely API
`links` in [Iframely API](https://iframely.com/docs/iframely-api) is the list of objects with fields `rel`, `href`, `type` and `media`. Just like you would expect a `<link>` in `<html>` `<head>` of the page to be.
Links are used as the raw data which you can use to select a widget. `html` field is there as the generated responsive embed code.
Example of a link object:
{
// SRC of embed. The main attribute
"href": "//coub.com/embed/2pc24rpb",
// functional and technical use cases.
"rel": ["player", "autoplay", "html5"],
// MIME type. Tells: "embed as iFrame"
"type": "text/html",
"media": { // Media query. Mostly responsive
"aspect-ratio": 1.777778
},
// plus generated or native HTML code:
"html": "<div ..></div>"
}
At times, Iframely will return `html` attribute without `href`. For example, for Twitter and Facebook Statuses, or elsewhere with very specific embed codes.
Also, Iframely does not generate `html` field for `image/*` MIME types.
Below is the list of possible `rel` values as well as information about `media` queries.
## Functional Rels
`rel` object contains an array of functional and technical use cases. You may decide which link works better for the use of your app.
Possible primary rels:
- `player` - widget with media playback. Like video or music or slideshow players;
- `image` - sizeable photo or picture, indicating that this is the main content on the web page. For use in e.g. photo albums "details" page;
- `app` - general extract for an app. For example, Twitter statuses, Facebook posts, Instagrams, etc;
- `thumbnail` - the preview image, usually smaller size;
- `reader` - text or graphical widget intended for reader functionality (e.g. article);
- `survey` - the widget is a questionnaire;
- `product` - the widget with the product information, usually has the "buy" link;
- `summary` - this rel is returned if widget is generated by Iframely as [summary card](https://iframely.com/docs/widgets);
- `file` - downloadable file. We return this rel for all direct links to files, including image files;
- `icon` - attribution favicon or glyph;
- `logo` - logo the source site. Is returned mostly for pages with the news article (custom ones) for better attribution.
[See some widget samples](https://iframely.com/docs/widgets). If embed was generated by Iframely via [URL Shortener](https://iframely.com/docs/url-shortener) as a [summary card](https://iframely.com/docs/widgets), the `rel` will be `summary`. If media embed was attached to URL from other provider (for example, player is embedded on that page), the `rel` array will contain `promo`.
## Technical Rels
Iframely also uses supplementary `rels` as the way to suggest technical aspects of the media:
- `autoplay` - if player starts media playback on its load;
- `ssl` flag indicates that embed media can be loaded via HTTPs;
- `html5` - if player is capable of HTML5 playback and will render ok on devices without Flash installed (for example, iOS);
- `inline` - for `app` indicates that embed widgets can be dynamically added to the page via JavaScript (e.g. doesn’t use `document.write`). Usually goes along with `html` field instead of `href` and indicates that html should be used as `srcdoc` of an `<iframe>` (as substitute to `href` as `src`).
- `gifv` - indicates that player represents a gif converted to MP4 and needs to be embedded as looping muted video.
These technical rels are result of our manual QA of the domains and are taken from our Domains DB (and therefore can change over time). For example, GitHub Gists were not `inline` the last time we checked.
### MIME Types
MIME `type` defines a suggested method to render link as widget. MIME type is an expected HTTP response `content-type` header of a resource behind `href` of a link. Type of content defines the rendering method.
There are following `type`s at the moment:
- `text/html` - widget needs to be rendered as `<iframe>`.
- `application/javascript` - JavaScript widget with dynamic page embedding with as `<script>`.
- `application/x-shockwave-flash` - Flash widget, we suggest to render with `<embed>`.
- `video/mp4` - HTML5 video. Will be rendered with as `<video>`.
- `image` and detailed `image/*` - this is image which will be rendered with as `<img>`. The detailed image type may be useful, for example, to detect GIFs.
## Sizes in Media Query
`media` section is for media query. Iframely generates query’s attributes as well as puts it into usable JSON.
Iframely outputs the following `media` query attributes at the moment:
- `aspect-ratio` - by far our favourite
- `max-width`
- `min-height`
- `min-width`
- `max-height`
- `width`
- `height`
For example, for `image` rel, Iframely will output exact sizes as `width` and `height` in `media` object.
## About responsive HTML code generation
The responsive HTML code for links will be generated by API on the server and added to the link object. The exception is the complementary thumbnails, icons and logos.
If you’d like to generate a responsive embed code yourself based on the raw data, please refer to:
- ["Responsive embeds"](http://amobil.se/2011/11/responsive-embeds/) by [Anders M. Andersen](https://twitter.com/andmag) / 2011
- [Creating Intrinsic Ratios for Video](http://alistapart.com/article/creating-intrinsic-ratios-for-video) by [Thierry Koblentz](https://twitter.com/thierrykoblentz) / 2009
- [How to Generate Responsive Embed Codes](http://iframely.com/oembed2/types) from Iframely Protocol