I am currently creating a set of custom media types for a RESTful api

Question

0

Asked: May 12, 20262026-05-12T09:21:53+00:00 2026-05-12T09:21:53+00:00

I am currently creating a set of custom media types for a RESTful api

0

I am currently creating a set of custom media types for a RESTful api (e.g. application/vnd.mycompany.foo+xml) and I’m trying to identify the pros and cons of two different ways of exposing hypermedia links.

If I first consider what other media types do probably the best place to start is HTML. Html allows me to create links such as:

<image src="http://example.com/image.gif"/>
<a href="http://example.com/page.html"/>
<form action="http://example.com/page.html"/>
<link rel="stylesheet" type="text/css" href="theme.css" />

The interesting thing here is that in some cases there some specific tags that have an url attribute and then there is the generic link tag that using the rel attribute to define the relationship.

In AtomPub, there are also a few ways that resources are linked together

<collection href="http://example.org/blog/main" >
         <atom:title>My Blog Entries</atom:title>
         <categories href="http://example.com/cats/forMain.cats" />
</collection>

<atom:category scheme="http://example.org/extra-cats/" term="joke" />
<atom:entry>
   <link rel="edit" href="http://example.org/edit/first-post.atom"/>
</atom:entry>

The question that I am asking is when does it make more sense to use a link element with a relationship, and when does it make more sense to add an attribute to an existing element.

e.g. the AtomPub links could have been done

<collection>
      <link rel="source" href="http://example.org/blog/main"/>
         <atom:title>My Blog Entries</atom:title>
         <categories>
                <link rel="source" href="http://example.com/cats/forMain.cats"/>
         </categories>
</collection>

<atom:category term="joke">
     <link rel="scheme" href="http://example.org/extra-cats/"/>
<atom:category>
<atom:entry edit="http://example.org/edit/first-post.atom"/>

As is frequently the case, in writing this question, the answer seems now to be obvious. The required links are exposed as attributes and optional ones as elements. However, I would be very interested in hearing other people’s opinions about how they think links should be represented.