search

raml-org / raml-spec

RAML Specification
http://raml.org
3.87k stars 858 forks source link

A way to describe patterned response code #584

Open petrochenko-pavel-a opened 8 years ago

petrochenko-pavel-a commented 8 years ago

Some times only range of response code is known, in RAML 0.8 it was possible to us X pattern to model it:

responses
  2XX:
     #my response

As for me it would be nice to have this feature back in RAML 1.0

Regards, Pavel

sichvoge commented 8 years ago

Hi Pavel, that was not possible in 0.8 according to the spec. How would you imagine an implementation (eg you generate a client or you do validation checks) will work on that?

petrochenko-pavel-a commented 8 years ago

Yep, you are right, I mismemoried it with X-{?} construct for headers.

How would you imagine an implementation (eg you generate a client or you do validation checks) will work on that?

As for me it is pretty clear, client should check response code against regexp where X symbols are replaced on any digit.

Regards, Pavel

freddrake commented 8 years ago

This seems like a somewhat strange thing to want to wildcard, but let's assume it makes sense for your application(s).

Do you imagine being able to use the X wildcard for arbitrary positions in the response code, or would you only expect to be able to use X for trailing positions? Should XXX or X00 be considered valid? How about 3X1?

petrochenko-pavel-a commented 8 years ago

P.S. you are right it is pretty rare usecase

or would you only expect to be able to use X for trailing positions?

yes

Actual usecase that I have in mind is the following:

I have existing API documentation which does not specifies actual response codes for operations and I would like to write a RAML spec for it. From documentation it is pretty clear when '2xx' response codes are expected, but it is not possible to guess exact response code so I need to write all of them or alternatively have some patterned code which marks all 2xx range response codes as allowed.

Regards, Pavel

freddrake commented 8 years ago

My understanding is that RAML is intended for writing specifications for APIs. It's not clear whether that's your intent with your project. You're attempting to describe a specific API which (apparently) isn't completely known.

This feels like you're interested in documenting what's known about an API, including the holes in knowledge. An interesting twist.

Perhaps the places where you can't adequately describe the API should inform a list of questions that can be asked about the API? If the API is produced within your organization, it shouldn't be too difficult to get questions answered. Otherwise, if may provide an opportunity for opening up better communication with the organization that provides the API.