Streamline content negotiation

[elmerbulthuis]

One very cool feature that http has is content negotiation! OpenApi42 embraces this by providing content negitaiotio as a first class citizen. It does need a little bit of streamlining.

current situation

export function createOperatioHandler(
  context: common.application.Context,
): api.OperationHandler<{}> {
  return async (incomingRequest, authentication, accepts) => {
    // do something to get message
    const message = "hi";

    for (const contentType of accepts) switch (contentType) {
        case "application/json": return {
            status: 200,
            parameters: {},
            contentType,
            entity() {
              return { message };
            },
          };
        case "text/plain": return {
            status: 200,
            parameters: {},
            contentType,
            value() {
              return message;
            },
          };
      }

    throw new Error("did not expect to get to here");
  };
}

We want to not manually throw the error. We can do this by allowing undefined to be a result of the operatinhandler. This should throw an error that can be translated by the error middleware into a 406 not acceptable.

Now content negotiation is somewhat verbose but this is considered an advanced feature, it requires some extra work for some extra relatively complex functionality. On could also designg their in a way that every content type has the same structure. That way the negotiation would be implicit. Like this:

export function createOperationHandler
  context: common.application.Context,
): api.OperationHandler {
  return async (incomingRequest, authentication, [contentType]) => {
    const message = "hi";

    return {
      status: 200,
      parameters: {},
      contentType,
      entity() {
        return { message };
      },
    };
  };
}

This will take the first (the preferred) content type from the accept header and use that in the response. Would be great if this could be implicit as well.