0

Is it a good idea to show documentation of a particular REST resource if clients Content-Type is other than application/json? I mean, if a developer tries to fetch a REST resource URL in browser he gets something like this.

speechkey
  • 625
  • 2
  • 10
  • 16

1 Answers1

0

Although this is open for discussion but in my opinion that would be a bad idea. The whole purpose of a RESTful API is to expose your application interface for other developers to use. Some developer look at http header to determine if certain route of your REST API existed regardless of the content-type. If I request for a text/plain, I would expected to receive a 404/NotFound if you don't have it and not a documentation with a 200/OK. Although, I suppose it could be useful for manual API testing with browser.

Infinity
  • 3,695
  • 2
  • 27
  • 35
  • Yes, your point has occurred to me. For testing API with a browser you can simply change your Content-Type in browser and test it and you normally wouldn't even try to use API with Content-Type other than application/json. But if you try it, ok no problem, you get documentation and see why are you wrong. – speechkey Dec 25 '12 at 16:53
  • Let says I wrote a program to request a text/plain content-type on your api, and on success (200/ok) I want it to deposit $100 into user account otherwise don't. In your case, it will return (200/ok) regardless even though that route doesn't existed. On large scale application, developers have to deal with lots of different RESTful API, you can't expect them to tailor their code to yours. Note that, it's the program that interact with your API; so, it can't say "oh, there is a doc on that page". – Infinity Dec 25 '12 at 17:07
  • 1
    Ok, you are right. If one gets an Ok, but the result of this action is opposite to the HTTP Status code, this is bad. It should definitely ends with a media type error (415). – speechkey Dec 25 '12 at 17:28