Optional responses

[mpfau]

Hello all and @sichvoge, it was perfectly valid to mark responses as optional in RAML 0.8. We made extensive use of this to provide libraries for error handling. We would be very happy if this feature could be re-enabled (there was already support for it in the 1.0 raml parser, until it has been removed recently).

Are there any reasons for not allowing optional responses?

Simple example (we also set bodies etc. in reality):

#%RAML 1.0
title: optional-bug
traits:
  throwingErrors:
    responses:
      400?:
        description: Bad Request
      404?:
        description: Not found
/test:
  post:
    is: [ throwingErrors ]
    responses:
      400:

Reference to original issue: #https://github.com/raml-org/raml-js-parser-2/issues/436

[mpfau]

Hi there, we still use optional responses for two main purposes:

• Provide a trait with all possible error definitions to reduce repitition
• Provide a lib with traits for basic response patterns.

@sichvoge Is there anything (either semantically or technically) that keeps us from allowing optional responses? If not, can you make the change to the spec?

Thanks!

[sichvoge]

Moving it to 'idea'.

@mpfau that feature had been removed to avoid any ambiguity we have seen with some examples. Hence, we restricted marking nodes optional only to methods. We could think about adding response codes to the possible optional marks, but we also need to see if there are any drawbacks.

BTW, in 0.8 you could possible mark all nodes in resource types and traits as optional. Again, we found that to ambiguous and changed it.

[linuradu]

Hi @sichvoge,

Would be great to add the possibility of having optional responses.

[jstoiko]

I don't understand the value in having optional responses. I feel like there is more value in NOT having the ability to set optional responses. Let me expand on that.

One can define:

#%RAML 1.0
title: optional-bug
traits:
  throwingErrors:
    responses:
      400:
        description: Bad Request
      404:
        description: Not found
/test:
  post:
    is: [ throwingErrors ]

which may be a very valid scenario if, for example, you had a gateway/proxy in front of that API and that API was offline for example, which would return a 404. In any case, I think it would be wise to define all the status codes in the API spec, even the least likely, since a client SDK generated from that RAML for example would be better off expecting more statuses than not enough.

But say that 404 was really an impossible scenario for that POST, "NOT having the ability to set optional responses" will force me to group those traits by methods which would be better (IMO) than leaving it up to each method to override each status individually. E.g.

#%RAML 1.0
title: optional-bug
traits:
  throwingGetErrors:
    responses:
      400:
        description: Bad Request
      404:
        description: Not found
  throwingPostErrors:
    responses:
      400:
        description: Bad Request
/test:
  get:
    is: [ throwingGetErrors ]
  post:
    is: [ throwingPostErrors ]

I may very well be missing something so please feel free to counter-argue, if possible by providing examples.

[linuradu]

@jstoiko thank you for your answer :)

As you described here, makes sense to define as you defined; let say in case of POST/PUT we have the 409 response. I have (POST/PUT)API methods where I don't have the 409 response and I have API methods where I have 409 response. How do you suggest to tackle this situation?

[jstoiko]

How do you suggest to tackle this situation?

Like my example above show: say you had a trait defining a 409 response, you would either apply or NOT apply that trait on methods you would like to have the 409 or NOT.