Telemetry for unmatched Endpoints

[d-s-d]

It would be convenient if it was possible to asses for what reason an endpoint did not match. For example: If part of your API is versioned, you might want to differentiate between a request that did not match any paths (in which case the API responds 404 or 405) and one that matched a path but the client's version was outdated (e.g., 410).

To further clarify what I'm aiming at, here is how I currently solve the problem. I use a custom endpoint that checks a header-value and sets a field in the context of the finagle request if the endpoint did not match. This value is then read in a finagle filter and a corresponding response is constructed. Below you can find the sourcecode for a possible implementation of such a version-endpoint:

// this endpoint should be applied after all paths.
final case class VersionEndpoint(apiVersion: Int) extends Endpoint[HNil] {
  private[this] val apiVersionString = apiVersion.toString

  override def apply(input: Input): Result[HNil] = input.request.headerMap.get("X-API-VERSION") match {
    case Some(s) if s == apiVersionString =>
      EndpointResult.Matched(input, Trace.empty, EmptyOutput)
    case _ =>
      input.request.ctx.update(VersionEndpoint.versionUnmatched, true)
      EndpointResult.NotMatched
  }
}

object VersionEndpoint {
  val EmptyOutput: Rerunnable[Output[HNil]] =
    new Rerunnable[Output[HNil]] {
      override val run: Future[Output[HNil]] = Future.value(Output.payload(HNil))
    }

  val versionUnmatched: Request.Schema.Field[Boolean] = Request.Schema.newField[Boolean]
}

[vkostyukov]

This is interesting. How popular is this HTTP 410 and the version header pattern?

We're generally trying not to be opinionated about certain decisions when it comes to structuring HTTP apps. While both 405 (MethodNotAllowed) and 415 (UnsupportedMediaType) seems to be generic enough to provide support from within a library, I don't feel so sure about 410 (Gone).

[d-s-d]

I haven't seen any API that actually uses 410 in the wild. Versioning seems to be one of these infamous problems that everyone solves on his own. ;-)

However, there are opinions about this matter out there, e.g.: https://webmasters.stackexchange.com/questions/71152/what-is-the-correct-http-status-code-for-this-version-of-this-api-has-been-dis