Home/ Questions/Q 6965177
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-27T16:01:22+00:00

While building a RESTful API of my web service I’m trying to give clients

  • 0

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?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    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

    • 0