How to document and return multiple successful statuses?

[haimgel]

Hello,
It's easy to specify multiple error statuses with u.SetExpectedErrors(...), and I can override the "success" status with nethttp.SuccessStatus(http.StatusCreated) when creating the handler. But: my API needs to return either 200 or 201 status based on some logic, with essentially the same JSON response.

I cannot find a way to do that nicely: I don't want to override the whole response serialization, and I don't think treating 200 or 201 as an "error" is the right approach. Any ideas?

[vearutop]

This is a tricky question.

With current implementation, I don't see any other options except implementing usecase.OutputWithWriter and overriding response serialization to get control over status code.

And for docs to use handler annotation to add new response type.

	s.Get("/my-endpoint", myUsecase(),
		nethttp.AnnotateOperation(func(op *openapi3.Operation) error {
			return s.OpenAPICollector.Reflector().SetJSONResponse(op, new(myStruct), http.StatusCreated)
		}),
	)

We can try to define (and implement) a better way of handling such case.

Though this is not so straightforward to generalize if you want a flexible solution, potentially one would want to have different status codes, content types and content structures (maybe I'm missing something else) in a single handler.

For served content, type and status code we can introduce an interface to be implemented on output type and used by response encoder, for example

type HTTPMultiJSONResponder interface {
  JSONContent() interface{}
  ContentType() string
  StatusCode() int
}

(this can also be 3 separate interfaces to allow better precision).

However, I don't see a convenient way to expose docs, i.e. to list multiple successful responses with their statuses and properties (there could also be multiple content types under single status code).

For this task nethttp.AnnotateOperation (as in the example above) seems to be already "good enough", although it lacks centralization on the output type (you need to set up docs separately from the usecase).

Perhaps we could use usecase instance wrap to pass additional info. Something like

u = nethttp.WithResponse(u, new(myStruct), "application/json", http.StatusCreated)

If you have any comments or other ideas how to solve this problem in a convenient way, please share.

[haimgel]

Thank you for your thoughtful answer, and for this great library in general! I think the root of the problem is that this library (together with usecase) is optionated, and I'm trying to use it in a way not originally intended. I agree with its opinions in general, having one response schema is a sound API design. In OpenAPI, all responses are created equal, but I'd rather not work with (or create) an API that can return different content types in its successful responses...

Response HTTP statuses, OTOH, are different matter. I'm creating an idempotent API that can return the same JSON object and will only indicate through its HTTP status (200 or 201) whether a resource was created or not. I think it's a fairly common pattern for PUT requests in particular, and it would be quite nice if this library was able to handle it without too many manual overrides.

So, in my mind, the following is needed:

• An optional interface on output to communicate the desired successful HTTP status to the encoder (as you mentioned).
• A way to communicate the possible HTTP statuses for OpenAPI. Even though it can be done the way usecase manages errors with SetExpectedErrors , I think HTTP status is not really a usecase concern. So maybe make this interface above return both the HTTP status and all possible HTTP statuses for this output? E.g.

type HttpStatusResponder interface {
  StatusCode() int
  ExpectedStatusCodes() []int
}

I think another option would be to encode HTTP status in a field in output with some magic annotation, e.g. header:"http-status", but this feels quite hacky.

What do you think?

[vearutop]

Makes sense to me, such an interface can be a good starting point for a relatively common case.

And in the future, if/when needed, we can complement it with something like:

type HTTPMultiResponder interface {
   StatusResponse(statusCode int) (content interface{}, contentType string)
}

for both docs and encoder.

I'll try to implement your proposal some time later, or send a PR if you'd like.