REST endpoint, dispatch to a method by header-value

[jmini]

Most of the webhook emitter applications are sending different webhook events (represented by different java classes) to the same url. Often there is a header for example X-Gitlab-Event indicating which type of event is sent.

List of all the events you can get from GitLab:
https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html

I am curious what you recommend for this kind of implementation with Java.

As far as I know, no matter what you use Quarkus REST, Quarkus Reactive Routes or the Spring Web annotations in Quarkus there is no way to dispatch a request to a java method by checking an header value.

You can get the value of a given header @RestHeader or @HeaderParam but then you still need to write the switch and somehow you need to de-serialise manually.

Something like:

    @POST
    @Path("/webhook")
    public Response webhook(@RestHeader("X-Gitlab-Event") String eventType,
                            byte[] body) {
        switch (eventType) {
        case "Push Hook":
            return handlePushHook(convert(body, PushEvent.class));
        case "Tag Push Hook":
            return handleTagPushHook(convert(body, TagPushEvent.class));
            //...
        default:
            throw new IllegalArgumentException("Unexpected eventType value: " + eventType);
        }
    }

But you need to write the convert(..) method manually (that is calling a deserializer like Jackson).

The situation can be a little bit improved if all your models share a common interface:

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, visible = true, property = "object_kind")
@JsonSubTypes({
    @JsonSubTypes.Type(value = PushEvent.class, name = PushEvent.OBJECT_KIND),
    @JsonSubTypes.Type(value = TagPushEvent.class, name = TagPushEvent.OBJECT_KIND),
// ...
})
public interface Event {
}

But you still need the switch case and the cast:

   @POST
   @Path("/webhook")
   public Response webhook(@RestHeader("X-Gitlab-Event") String eventType,
                           Event event) {
       switch (eventType) {
       case "Push Hook":
           return handlePushHook((PushEvent) event);
       case "Tag Push Hook":
           return handleTagPushHook((TagPushEvent) event);
           //...
       default:
           throw new IllegalArgumentException("Unexpected eventType value: " + eventType);
       }
   }

Ideally I would like to do something like:

  @POST
  @RestHeaderMapping(key = "X-Gitlab-Event", value = "Push Hook")
  @Path("/webhook")
  public Response handlePushHook(PushEvent event) {
      // ...
  }

  @POST
  @RestHeaderMapping(key = "X-Gitlab-Event", value = "Tag Push Hook")
  @Path("/webhook")
  public Response handleTagPushHook(TagPushEvent event) {
      // ...
  }

[jmini]

An other pattern where something like @RestHeaderMapping could be useful is API versioning based on header value (like Api-Version).

See API versioning: URL vs Header vs Media Type versioning

This way you could do something like:

  @POST
  @RestHeaderMapping(key = "Api-Version", value = "v1")
  @Path("/resource")
  public Response v1Ressource(V1Resource body) {
      // ...
  }

  @POST
  @RestHeaderMapping(key = "Api-Version", value = "v2")
  @Path("/resource")
  public Response v2Ressource(V2Ressource body) {
      // ...
  }

Right now implementing header based versioning is quite difficult to achieve, exactly because of this "routing" difficulty. And this is why people prefers implementing path-based (or URL based) versioning.