Support for operations that respond with 1xx status codes

[HenryGessau]

Is your feature request related to a problem? Please describe.

Some APIs have operations that respond with 1xx instead of 2xx status codes. A common example is 101 Switching Protocols for supporting WebSockets.

A design utilizing 1xx status codes is not indicative of a bad API, and should therefore be accepted by the recommended ruleset. However, it runs afoul of the recommended operation-2xx-response rule.

Describe the solution you'd like

I see a couple of possibilities:

• Replace the recommended rule with a new operation-2xx-or-1xx-response.
• Add a configuration like alsoAllow1xxResponse to the operation-2xx-response rule.

I am sure there are other viable approaches.

Describe alternatives you've considered

I could configure an override for my specific operations that return 101. However, it feels wrong to have this configuration for an otherwise good API.

Additional context

Not all 1xx status codes are equally good. In particular, 102 Processing is deprecated.

[lornajane]

Thanks for the question! The recommended ruleset is aimed at being a solid recommendation for people with a basic API and little knowledge about APIs, to get them started in their API governance journey. Once up and running, almost all organisations should adjust the ruleset to fit their context, and I think that's the best approach here.

I'll close the issue since there's no action planned on our side, but please stay in touch if you have more comments or questions for us.

[meem]

@lornajane Understood on the goals of the recommended ruleset, but to be clear: we consider the operation-2xx-response rule generally quite valuable - e.g., we have hundreds of operations in our API and only a couple that make use of 101. Is there a way for us to off the check for a specific method (similar to being able to specify JSON pointers with Spectral rule overrides? That would enable us to keep the rule on in general while keeping the recommended ruleset simple.

[lornajane]

Yes there is! You can set an ignore for just the specific things you want to avoid having reported. The docs you want are over here: https://redocly.com/docs/cli/commands/lint/#generate-ignore-file

[HenryGessau]

@lornajane Unfortunately, with the ignore file approach, I end up with a problem similar to that described by #1224, as we generate multiple variants of our API (and furthermore, in our CI they are generated in temporary directories).

The solution in #1224 seems to be to create a custom plugin with an extension, but it is not clear to me how to write an extension for operation-2xx-response. Do you have any suggestions?

[tatomyr]

Hi @HenryGessau, there is yet another option to solve your case. While you can still use the recommended ruleset as your base, you can turn the severity of that specific rule to off and write your own configurable rule like this:

extends: 
  - recommended
rules:
  operation-2xx-response: off
  rule/operation-1xx-or-2xx-response:
    subject: 
      type: Responses
    assertions: 
      requireAny: 
        - '101'
        - '200'
        - ...

And then add as many required response codes as you need (probably all 2xxs and maybe even the default one). See more about configurable rules here.
This will ensure that every operation will have to contain at least one of the enlisted response codes.