Databases
StackOverflow2013
Postsdbo
PO
 

Note that there are some explanatory texts on larger screens.

plurals
  1. PO
    primarykey
    data
    text
    <p>There are a few main signaling mechanisms you can use in a RESTful service:</p> <ul> <li>The media type</li> <li>The <code>rel</code> of a resource you are linking to.</li> <li>Custom headers, like <code>Accept-Version</code>/<code>Api-Version</code>.</li> </ul> <p>Each of these has distinct uses, and I will outline the ways in which we have come to understand them while designing our API.</p> <hr> <h2>Media Types</h2> <p>To signal what operations are possible on a given resource, and what the semantics of these operations are, many use custom media types. In my opinion, this is not quite correct, and a <code>rel</code> is more accurate.</p> <p>A custom media type should tell you about the <em>type</em> of the data, e.g. its format or the way certain information is embodied or embedded. Having a custom media type means consumers of your API are tightly coupled to that specific representation. Whereas, using something more generic like <code>application/json</code> says "this is just JSON data."</p> <p>Usually JSON alone is not enough for a RESTful service, since it has no built-in linking or resource-embedding functionality. That is where something like <a href="http://stateless.co/hal_specification.html" rel="noreferrer">HAL</a> (<code>application/hal+json</code>) comes in. It is a specialization of JSON that is still a generic format, and not application-specific. But it gives just enough to overlay the linking and embedding semantics on top of JSON that is necessary for coherently expressing a RESTful API.</p> <h2>Link Relation Types (<code>rel</code>s)</h2> <p>This brings us to <code>rel</code>s. To me, a custom rel is a <em>perfect</em> way to signal what type of resource is being dealt with or linked to. For example, a custom <code>rel</code> for a user resource might be <code>http://rel.myapi.com/user</code>, which serves two purposes:</p> <ul> <li>Clients of your API must know this key ahead of time, as it is API-specific knowledge. For example, if it was available on your initial resource and you were using HAL to link to the user resource, clients might find the user link via <code>initialResource._links["http://rel.myapi.com/user"].href</code>.</li> <li>Developers <em>writing</em> API clients can visit that URI in their web browser, and get an explanation of what that resource represents in your API, including what methods are applicable and what they do. This is a very convenient way to communicate that API-specific knowledge I mentioned. For examples of this, see <a href="http://rel.nkstdy.co/" rel="noreferrer">http://rel.nkstdy.co</a>.</li> </ul> <p>If you combine <code>rel</code>s with a standard or semi-standard media type like <code>application/hal+json</code>, you get resources which follow a uniform format specified by their media type, with API-specific semantics defined by their <code>rel</code>s. This gets you almost all the way there.</p> <h2>Custom Headers</h2> <p>The remaining question is versioning. How do you allow clients to negotiate different versions of the resource, while not invalidating old URIs?</p> <p>Our solution, inspired by the <a href="http://mcavage.github.com/node-restify/#Routing" rel="noreferrer">Restify</a> Node.js framework, is two custom headers: <code>Accept-Version</code> from the client, which much match <code>X-Api-Version</code> from the server (or <code>Api-Version</code> in the upcoming Restify 2.0 release, as per the new <a href="http://tools.ietf.org/html/rfc6648" rel="noreferrer">RFC 6648</a>). If they don't match, a <code>400 Bad Request</code> is the result.</p> <p>I admit that custom media types are a fairly popular solution here. In my opinion they don't fit very well conceptually, in light of the above considerations, but you would not be doing something weird if you chose them as your versioning mechanism. It has some semantic issues when used with methods other than <code>GET</code> though, as you note.</p> <p>One thing to keep in mind is that in a truly RESTful system, versioning should not be such an issue. It should only matter in one very specific situation: when the representations of your resources change in backward-incompatible ways, but you still want to keep the same <code>rel</code>s. So if the <code>http://rel.myapi.com/friend</code> resource suddenly loses its <code>username</code> field and gains an <code>id</code> field, that would qualify. But if it suddenly gains a <code>nickname</code> field, that's not backward-incompatible, so no versioning is needed. And if the concept of "friends" is completely replaced in your API with the concept of, say, "connection", <em>this is not actually backward-incompatible</em>, because API consumers will simply no longer find <code>http://rel.myapi.com/friend</code> links anywhere in the API for them to follow.</p>
    singulars
    1. This table or related slice is empty.
    1. POIs the usage of custom media types a good option?
      singulars
      1. PTQuestion
    1. PTAnswer
    1. This table or related slice is empty.
    1. USDomenic
    plurals
    1. This table or related slice is empty.
    1. This table or related slice is empty.
    1. POIs the usage of custom media types a good option?
      singulars
      1. PTQuestion
    1. This table or related slice is empty.
    1. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    2. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTAcceptedByOriginator
    3. VO
      singulars
      1. PO
      1. This table or related slice is empty.
      1. VTUpMod
    1. COThanks Domenic for such a thorough reply.
      singulars
      1. PO
      1. USFinalFive
    2. CO[Domenic](http://stackoverflow.com/users/3191/domenic), I'm surprised you're using link relations to indicate the destination type. I would have expected them to indicate the type of the relationship between the source and destination. cf. <http://microformats.org/wiki/existing-rel-values>
      singulars
      1. PO
      1. USMatt McClure
    3. CO@MattMcClure that's actually a really good distinction that I'd never thought about before. Still, I'm not sure what I'm doing is inaccurate: for example, if a user owns a document, would it be inaccurate to call the link relation "document"? Would you prefer "owned" or similar? Hmm.
      singulars
      1. PO
      1. USDomenic
 

Querying!

 
Guidance
A row detail

Detail views are divided into sections. All the information in the data section comes from columns in the selected row. The other sections display data from other, related rows.

Related data can be related in a to-one or a to-many fashion. Captions of data related in a to-many fashion link to a list view showing a filtered view of the table.

Try moving around until you find a non-empty to-many entry and click on the label to get to one. You can move back to the root by clicking on the database name in the header.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload