Skip to main content
Version: Latest (0.56.x)

Content types

Default behavior​

Content type is assumed to be application/json by default regardless of the type of the request or response body.

Examples:

op download(): bytes; // Returns a json string with the bytes serialized as a base64.
op getContent(): string; // Returns a json string
op getPet(): {
  // Json object with a name property.
  name: string;
};

Specify content type​

The content type for an operation can be specified by including a header parameter named contentType.

Request content type​

op uploadImage(@header contentType: "image/png", @body image: bytes): void;

Response content type:​

op downloadImage(): {
  @header contentType: "image/png";
  @body image: bytes;
};

Multiple content types​

If there is multiples content types for the same body, they can be specified using a union of string.

op uploadImage(@header contentType: "image/png" | "image/jpeg", @body image: bytes): void;

Content type negotiation​

There could be cases where you might the same endpoint to return different content depending on the content type requested. This can be achieved in 2 ways:

  • using shared routes where different content response is represented as a different operation that share the same endpoint
  • using overloads where each different content response is an overload.

For example assuming there is an api that lets you download the avatar as a png or jpeg which is decided by what Accept header is sent.

Option 1: Using shared route​

model PngImage {
  @header contentType: "image/png";
  @body image: bytes;
}

model JpegImage {
  @header contentType: "image/jpeg";
  @body image: bytes;
}

@route("/avatar")
@sharedRoute
op getAvatarAsPng(@header accept: "image/png"): PngImage;

@route("/avatar")
@sharedRoute
op getAvatarAsJpeg(@header accept: "image/jpeg"): JpegImage;

Option 2: Using overload​

model PngImage {
  @header contentType: "image/png";
  @body image: bytes;
}

model JpegImage {
  @header contentType: "image/jpeg";
  @body image: bytes;
}

@route("/avatar")
op getAvatar(@header accept: "image/png" | "image/jpeg"): PngImage | JpegImage;

@overload(getAvatar)
op getAvatarAsPng(@header accept: "image/png"): PngImage;

@overload(getAvatar)
op getAvatarAsJpeg(@header accept: "image/jpeg"): JpegImage;

Multipart request​

See Multipart docs