oEmbed

oEmbed "is a format for allowing an embedded representation of a URL on third party sites."

You provide a resource URL (and optionally some parameters) to a service URL, and the service URL returns XML, JSON or HTML which you can use to render an embedded representation of that resource.

What's wrong with just using HTTP's existing mechanisms for this? Why invent something new?

Here's how the default oEmbed example (no parameters, returning the JSON default) could work using stock HTTP:

Accept headers are designed to request specific representations of resources. Provide an IANA content type and any parameters separated by semicolons. We use the oEmbed parameter, since without it we might get a JSON representation of the page, instead of a JSON representation of the embedded version. That request is 100% unambiguous for a server that understands it, and anything else should return 406 Not Acceptable.

Valid responses work the same. The only difference is optimized requests and no need for a separate service handler. You could even specify the version number along with the oEmbed parameter.

oEmbed specifies an optional cache_age response item. Why? HTTP already has Expires.

Service discovery could be improved if, instead of creating something new, you resurrect older HTTP headers from previous or experimental RFCs. RFC 2068 (the first HTTP/1.1 RFC) provided for alternate representation descriptions at the header level, saving you from HTML-based autodiscovery. While left out of RFC 2616, the Alternates header was not explicitly deprecated (although URI was), and experimental RFC 2295 provides a syntax for it. Instead of publishing service URLs, you could just make a HEAD request against the desired resource and receive something like:

The empty string is a valid relative URI representing the current URI. 0.0 is the quality of the representation: specifying an essentially useless quality ensures it will not be accidentally or automatically selected by a user-agent. The content type follows, either JSON or XML, per the oEmbed specification. Finally, the features tag list specifies the oEmbed nature of the alternate resource (the features tag list is used to define a property or explain the quality of the variant). We could also use an extension attribute instead:

The x- prefix denotes an experimental extension; this would not necessarily be necessary in this case of a proper extension. The version number token could provide the client with complete understanding of the server's response, particularly in the case of future oEmbed versions.