CODEWITHSUNDEEP
apiresturihyperlink
Appelsien S.
Appelsien S.

Reputation: 281

REST - how to format the links in content

In REST, it's all about links. Basically, the API user only needs one link, the top-level link. This is usually http://server/api/ or something alike. All other links are discovered while browsing through the hierarchy. For example, GET /api/ might give you a link to /api/users/ and /api/images/ and /api/users/ might give you a link to /api/users/john/, and so on.

That said, I am wondering if there is some kind of standard how to format these links. After all, if it is all about links, a crawler should be able to discover all the resources in the system by starting at the top?

I did some researching wrt. the XML media type, and couldn't find any noted standards. Let's pick the /users/ resource. Some write

<users>
    <user name='john' uri='/users/john'/>
    <user name='steve' uri='/users/steve'/>
</users>

Others write

<users>
    <user name='john' link='/users/john'/>
    <user name='steve' link='/users/steve'/>
</users>

Others use xlink, which gives for example:

<users>
    <user name='john' xlink:href='/users/john'/>
    <user name='steve' xlink:href='/users/steve'/>
</users>

And so on.

I might be ignorant here, but shouldn't there be some kind of standard which specifices how to format your links to the other resources, so there isn't any knowledge on how the data is formatted required? In other words, crawler X for the API of application A1 will probably not work for the API of application A2, since A1 formats its links to its resources differently than A2.

In the above, I was only talking about the XML media type. When you take JSON, there are even more versions spread in the field.

Why didn't REST specify how the links to related resources of a resource should be formatted?

Upvotes: 4

Views: 1112

Answers (2)

Darrel Miller
Darrel Miller

Reputation: 142014

The problem with returning application/xml is that there are no standard semantics defined for specifying a link. That's why it is not a very good hypermedia media type. Xhtml is a better one that does specify some rules for links. HAL is another good one that is even simpler.

There are many things to consider when specifying a link in a document, far more than just the href. Mike Amundsen has done some great work with hfactor talking about the various aspects of embedding links into documents.

The most important part of a link is as John Howes mentioned the rel. The rel can either be a global defined one like the ones defined here as IANA. Or they can be your own custom ones as long as you follow the rules for Extended link Relations as defined in RFC 5988. The rel documentation tells the client developer all he or her needs to know about activating that link.

Upvotes: 5

fumanchu
fumanchu

Reputation: 14559

Why didn't REST specify how the links to related resources of a resource should be formatted?

Darrel has a good take above, but to answer your question directly: REST is a style, that is realized in an architecture, that makes use of protocols, that take advantage of media types. It is supposed to be the media type that specifies how links should be formatted. So REST itself doesn't specify formatting. It specifies how to constrain the arrangement of the interaction of data elements whose standard types specify link formatting.

Upvotes: 2

Related Questions