responses vs apiResponses vs pathResponses

[matthewtrask]

hey y'all,

I know I've been away for sometime so apologies there. I started seeing these rumblings pop up on twitter which made me excited but then I saw the example (which I know is in a very rough/beginning state) and had to wonder if there is something better to be done with responses vs pathResponses vs apiResponses? One thing I've always heard from people is that the specification is overly verbose and confusing., but maybe thats just me? If this is being talked about elsewhere then apologies but I didnt see it.

[kevinswiber]

@matthewtrask What would you want to see done? Any ideas?

[arno-di-loreto]

TLDR: That's probably just a bug/typo, let's rename them all responses (to keep things simple and avoid naming-side-effects across the whole specification).

Extended response:

The spec is in the early stage, and the current naming is probably just a "typo," or a consequence of "that looks clearer on the diagram." Or maybe there's a true intent behind it (if that's the case it would be interesting to know it).
Whatever the reason: naming a single property is hard, important, and may have consequences across all the design (works for a spec or an API).

As the three apiResponses, pathResponses, and responses describe the same thing (responses), but at a different level (API, path, operation), I would just name them all responses, it's the context/location that tells at which level they apply (parent property name or sibling properties giving a clue about the level).

I use that "avoiding prefix as much as possible" naming strategy for the sake of:

• Having the exact same name used for a "thing" (consistency and so understanding and usability)
  • It's human-friendly but also (dumb-)machine-friendly: "whatever the level no need to think, just look for response" vs "which level is this? then Response".
• Having shorter names (usability/readability).

Attention: Deciding on which name to choose for the property holding responses (apiResponses vs response) implicitly defines a naming pattern that should be applied across all the specification (<location>Thing vs thing).

So, if for any reason, the apiResponses, pathResponses would be kept that way, I would argue that:

• responses which is at the operation level should be renamed operationResponses
• the parameterSchemas which appears at the path and operation levels should be respectively renames pathParameterSchemas and operationParameterSchemas
• the contentSchema properties which appears on request and response should be renamed requestContentSchema and responseContentSchema
• and so on ...

(I think doing hundreds of API design reviews may have twisted my mind about consistency 🤪)

PS: Just like there should be guidelines regarding map vs list, there should be guidelines regarding naming (location suffix/prefix or not, type suffix/prefix, ...)

[matthewtrask]

@arno-di-loreto this is fantastic. I agree with everything you laid out.