Why multiple status codes are required in RAML response? - rest

Question

While defining RAML, in response body we will define response based on status codes like 200, 400, etc.
Why that seperate defination is required?
sample RAML
responses:
200:
body:
type: User
400:
body:
type: ErrorMessage
From controller i can send like
response = Request.CreateResponse(HttpStatusCode.Ambiguous, error);
This will create response as 300 status.
While hitting the api from Postman, i can able to get the response with status 300.
So Is it really needed to define the response for different status codes?

Answer 1

Is it really needed to define the response for different status codes?
RAML is a way of generating documentation and clients. Sure, you could document you're going to return a body of X and actually return a body of Y, but all that will cause is annoyed consumers.
So you could return the same response type for all response codes, or document when the response type varies per response code.

Answer 2

I think you are misunderstanding what RAML is.
RAML is documenting your API, it does not implement your API. So yes, you can have an implementation that is different from what your RAML specifies.
Is it really needed to define the response for different status codes?
No, in RAML the whole responses is optional. So you could just leave it out.
But the idea is that you specify RAML as close as your implementation as you can, so it is useful for you and other people.
While defining RAML, in response body we will define response based on
status codes like 200, 400, etc. Why that seperate defination is
required?
Different status codes usually mean different response data.
For example if you are getting a dog by id (/dogs/1) then if the dog is found you will return status code 200 and the body will contain data about the dog. e.g. { name: "foo", colour: "brown", ...}
On the other hand if there's no dog with id 1, then you will return status code 404 and in the body something like: { message: "a dog with id 1 was not found" }