Quick Start Guide


Jump to instructions for:



OExchange For Service Providers

If you manage a service that can accept URLs and do something useful with them (a "Target" in OExchange terms), here's what you need to know to support the protocol. There's also an example service you can take a look at.

1. Expose an endpoint to receive URLs in a standard way

First make sure that your service exposes a URL endpoint at which users, via their browsers, can send it content. Your endpoint needs to be compatible with the OExchange Offer specification. This just means that users can navigate to it with their browser, via an HTTP GET, and that it accepts the standard OExchange URL arguments. In simplest terms:

http://www.example.com/share.php?url={URI}

In this case, http://www.example.com/share.php is the Offer endpoint. Your service must accept the url parameter, but that's it. Depending on whether you accept richer content types, like images, you may want to accept additional parameters as well (but you don't have to). Note that your endpoint can be anywhere you want, at any URL, as long as it accepts the right parameters.

The Offer spec has all the extra details on the endpoint.

TIP: Take a look at our Best Practices and use the Offer Test Harness to test your endpoint.

2. Make your service discoverable

Now that third parties are capable of sharing content to your service, they need to be able to discover that your service exists, and locate its Offer endpoint. This is optional, but if you don't implement it then anyone that wants to share content to your service will have to look it up in documentation and integrate that way. The Discovery File Generator and Discovery Test Harness can help you set all of this up. Here's basically what you'll do.

Include the details of your service in an XML file, in a specific format (XRD). This file will contain things like the name, an icon, and some other information including the actual endpoint. Read about the complete format in the spec, or just take a look at an example. You can place this file on your domain anywhere you'd like.

To allow third parties to discover your service from its hostname, include a reference to the XRD file in your site's /.well-known/host-meta file. If you don't have one, its easy to create. Read more about it in the spec, or just look at an example.

Lastly, you can also add a specific HTML tag to any page on your site, to point to a related service. This works just like adding RSS feed indicators to your pages, for example. The tag will look something like the following, with an href that points to your service's XRD file.

<link rel="http://oexchange.org/spec/0.8/rel/related-target" type="application/xrd+xml" href="http://www.example.com/linkeater/oexchange.xrd"/>

You can read more about this tag and its purpose, as usual, in the spec.

TIP: Remember that the Discovery File Generator can help you generate all of the files you need, and the Discovery Test Harness can help you test compliance.

3. You're done.

Once you've got a compliant Offer endpoint, a Target XRD that describes your service, and a host-meta resource that lets it be found automatically, your service is ready to accept content from any client on the web!




OExchange For Publishers

If you're a site that has content to share (a "source" in OExchange terms), you can of course use one of the many sharing aggregators and tools that are out there. If you want to build your own sophisticated, personalized sharing options yourself, take a look at the information intended for these tools. If you just want to make your own icons and link to the URLs of various services, then all you need to do is link to their Offer endpoints directly. These look something like:

http://www.example.com/share.php?url={URI}

Once you know the core Offer endpoint, then the arguments will be the same no matter which services you are using. You can implement the most basic sharing icon like this:

<a href="{service offer endpoint}?url=http://www.example.com"><img href="{service image here}"></a>

OExchange means that every service accepts the same parameters, all that changes is the offer endpoint URLs; a big improvement over the range of URL patterns in use otherwise.

Usually, you will get the offer endpoint location from the service's documentation since you're not figuring it out dynamically at runtime. If you'd rather do it automatically, then you're operating more like a sharing tool and should probably take a look at that guide.




OExchange For Tool Developers

Want to start leveraging OExchange to share content? Things you need to know...

1. Targets accept content in a standard way

If you want to send content to an OExchange-compliant service, all you'll need to do is send the browser to the service's Offer endpoint. This is a URL that looks something like:

http://www.example.com/share.php?url={URI}

There are a bunch of optional parameters you can pass, but really url is the only one that's actually required. Take a look at the Offer spec for more information on the exact details of the Offer endpoint.

2. You can locate targets automatically

The more powerful capability of services that support OExchange is their ability to be discovered automatically. If you know a hostname, for example, you can figure out if there is a service that accepts links there like this:

  1. Look for a document at the host's /.well-known/host-meta path.
  2. If there is one, look for a Link element inside this, with a relation type of http://oexchange.org/spec/0.8/rel/resident-target.
  3. If there is one, this describes the path of a an XML document (or several) that describes the service.
  4. Look up that XRD document, which will describe everything about the service, including the URL for its Offer endpoint.

Read more about this discovery flow, and the formats of the two documents, in the specification. You can also take a look at the example LinkEater service, and even use the discovery Test Harness to check hosts automatically.

Additional options for locating services are by looking for meta tags in HTML pages that point to related services, or even using WebFinger to look up and record user service preferences. Take a look at the page metatag and personal XRD specifications.

3. The rest is your call

What you do with all these capabilities as a sharing tool is up to you, thats the value you're adding!