CODEWITHSUNDEEP
resthyperlinkhateoas
yegor256
yegor256

Reputation: 105203

How to create link relation for POST end point?

While building a RESTful API of my web service I'm trying to give clients link relations, for example (this is what a GET entry point returns):

<doc>
 <links>
  <link rel="self" href="/home"/>
  <link rel="post" href="/post-new-article"/>
 </links>
</doc>

I'm expecting the client to understand that in order to post a new article he has to submit a POST request to /post-new-article with "text" as query parameter.

But I didn't say anything about "POST" in the document, and I didn't tell him which HTTP query parameter I'm expecting. How and where should I provide this information? Is there any de-facto standard/convention about it?

Upvotes: 2

Views: 3122

Answers (1)

toddsundsted
toddsundsted

Reputation: 6365

The technically correct answer is that it is defined by the media type of the document. For example, assume the API serves HTML. And the client is a browser.

By convention, when a user-agent (browser) visits a resource (identified by an anchor tag) it issues an HTTP GET to the server serving the API. Assuming everything goes as planned, the server returns another HTML representation of that resource.

Likewise, when a user-agent submits a form it issues an HTTP GET by default unless the method attribute of the form tag indicates it should POST the data. (Details here.)

Your API documentation should specify in detail the media type your REST service uses. If it is a custom type then the specification should include the rules for following links. If your API runs over HTTP, then the rules would specify GET, POST, DELETE, etc. as well as any other requirements/conventions.

From Roy himself: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Upvotes: 3

Related Questions