forked from iamcal/oembed
/
draft_old.htm
82 lines (60 loc) · 3.54 KB
/
draft_old.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<html>
<head>
<title>oEmbed Drafts</title>
<style>
body, input, textarea, select {
font-family: Arial,Helvetica,sans-serif;
padding: 20px 50px;
}
pre {
background-color: #eee;
border: 1px solid #999;
padding: 8px;
margin: 1em 20px;
}
code {
background-color: #eee;
border: 1px solid #999;
padding: 0px 2px;
}
</style>
</head>
<body>
<h2>X. Discovery</h2>
<p>OEmbed providers can choose to make their endpoints discoverable by serving a file called <code>oembed-config.xml</code> in the root of their domain. For instance, Flickr could provider a discovery file at <code>flickr.com/oembed-config.xml</code>. The contents of the file should be as follows:</p>
<pre><?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed version="1.0">
<config ttl="24" />
<match pattern="{URL Pattern}" endpoint="{Endpoint URL}" type="{Type}" />
<match pattern="{URL Pattern}" endpoint="{Endpoint URL}" type="{Type}" />
</oembed></pre>
<p>The order of the different elements does not matter, except the relative position of any <code><match></code> elements. Consumers should test URLs against <code><match></code> rules from top to bottom.</p>
<p>The <code><config></code> element is optional. The <code>ttl</code> (Time-To-Live) property specifies a suggested cache time for the configuration, in hours. Consumers may choose to ignore this, however, and cache the configuration for as long as they deem appropriate. A TTL of 7 days is recommended for either <code>oembed-config.xml</code> files that don't contain a TTL, or <code>oembed-config.xml</code> files that return a 404 response. That is to say, consumers should cache the non-existance of a <code>oembed-config.xml</code> file for 7 days.</p>
<p>One or more <code><match></code> elements contain the URL pattern to API Endpoint mappings. The URL pattern should not include the scheme or domain - the scheme (HTTP or HTTPS) and domain are inferred from the URL to the XML file itself. The pattern and should start with a forward-slash and may only contain '*' as a wildcard (matching zero or more characters of any kind). The Endpoint URL should include the scheme, which must be HTTP. The Type specifies whether the endpoint expects to be passed a <code>format</code> argument (<code>explicit</code>) or whetherthe format is implied by the Endpoint URL itself (<code>xml</code> or <code>json</code>).</p>
<h3>X.1. Example oembed-config.xml configuration files</h2>
<p>Single rule configuration for flickr.com:</p>
<pre><?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed version="1.0">
<match pattern="/*" endpoint="http://www.flickr.com/services/oembed/" type="explicit" />
</oembed></pre>
<p>Multi rule configuration for qik.com:</p>
<pre><?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed version="1.0">
<match pattern="/video/*" endpoint="http://qik.com/api/oembed.xml" type="xml" />
<match pattern="/video/*" endpoint="http://qik.com/api/oembed.json" type="json" />
<config ttl="72" />
</oembed></pre>
<h3>X.2. oembed-config.xml DTD</h3>
<p>The following DTD can be used to validate <code>oembed-config.xml</code> files:</p>
<pre>
<!ELEMENT oembed (match+,config?)>
<!ATTLIST oembed version CDATA #FIXED "1.0">
<!ELEMENT match EMPTY>
<!ELEMENT config EMPTY>
<!ATTLIST config ttl CDATA "168">
<!ATTLIST match pattern CDATA #REQUIRED>
<!ATTLIST match endpoint CDATA #REQUIRED>
<!ATTLIST match type CDATA #REQUIRED>
</pre>
</body>
</html>