Clarify: respondWithStatus

[ktoso]

Hi @sirthias @jrudolph,
I realised we don't have respondWithStatus ported to Akka HTTP.
On this one I'm not sure if it's an omission by design or accident, WDYT?

See:

• http://spray.io/documentation/1.2.2/spray-routing/respond-with-directives/respondWithStatus/

Note to self ( remove // FIXME https://github.com/akka/akka/issues/18626 from code once resolved )

[ktoso]

PS: Sorry if I'm too noisy with all these "clarify" tickets – It's mostly so we're able to respond properly once people coming from spray start asking "hey, X is missing!", and I'm noticing those currently since documenting all directives.

I'm rather sure you made the right call when not porting something, just wanted to understand the reasoning behind it where it's not immediately clear to me 😄 Thanks in advance for the help!

[jrudolph]

I didn't remember we once had this directive and I cannot remember a reason for not having ported it or making any decision.

I think the main reason not to include it (despite seeming basic enough) would be that it isn't really useful in most cases. In most cases, you would first figure out the response status code before figuring out any other detail of the response, so the question would be why you would want to override it later on?

Common ways to specify the status code are:

• use 200 OK ;)
• use one of the marshallers that allows to specify a status code together with the entity body, e.g. as a Tuple statusCode -> entity
• build a complete HttpResponsecompletely including the status code
• reject a request and from a RejectionHandler return an HttpResponse including the (error) status code

I'm not against include responseWithStatus, but if it is included it should mention the more common ways of setting status codes.

[jrudolph]

And, no worries about the clarify tickets. They are easier to keep track of than reading through the chat and better for keeping the record for later questions, so 👍 for having them.

[sirthias]

I agree with @jrudolph, keep the clarify tickets coming, Konrad! :)

As to respondWithStatus we did not port it simply for the reason that Johannes stated:
There is probably no good reason to use it.
Overriding the status code coming back from an inner route appears hacky to me. You can do it, if you must, but we shouldn't "bless" it by providing a nice shortcut.

[ktoso]

For reference, we still have overrideStatusCode(201) which seems to do the same thing.

So we have it in that sense.
Strong enough opinions to remove it or keep as is, WDYT?

// cc @jrudolph @sirthias @rkuhn

[ktoso]

At the very least made it not recommended:

  /**
   * Not recommended directive, try to solve your problem by providing a custom [[RejectionHandler]] for example.
   * 
   * Overrides the response status code with the given one.
   */
  def overrideStatusCode(responseStatus: StatusCode): Directive0 =
    mapResponse(_.copy(status = responseStatus))

[jrudolph]

Ah those elusive little directives, I guess we probably just renamed it during the migration and no one could remember...

Regarding the ScalaDoc maybe switch the lines around so that the summary is still at the top. That said, I wonder if we should keep it if we have only harsh words for it. Seems inconsequential and unfair to the little one. If we cannot find a positive description that would offer at least one however far-fetched use case for it, we should set it free.

[ktoso]

Trying to be inventive I imagined this use case:

          authorize(quotaOk) {
            doThings()
          } ~
          overrideStatusCode(StatusCodes.EnhanceYourCalm) { // 420, e.g. used by Twitter
            doThings()
          } 

Not sure if that's realistic at all, rather not... 😉

[jrudolph]

It's still weird that you first build a full response just to get rid of it later on.

[ktoso]

Ok, since we can't find a good use case, I'll remove it.

[ktoso]

Removed, closing.

It's free now :-)