Skip to content

byos

Id
@azure-tools/typespec-azure-core/byos

Use the BYOS pattern recommended for Azure Services.

Operations that upload binary data (using content types like application/octet-stream or multipart/form-data) should use the Bring Your Own Storage (BYOS) pattern recommended for Azure Services.

See the Azure REST API Guidelines - BYOS for more details.

Impact

Section titled “Impact”
  • Area: API

The API transfers large artifacts through the service (upload/download) instead of using a storage account, which scales poorly and diverges from Azure guidance.

❌ Incorrect

Section titled “❌ Incorrect”

Uploading binary data with application/octet-stream:

op uploadFile(data: bytes, @header contentType: "application/octet-stream"): void;

Uploading with multipart/form-data:

op uploadFile(
  @multipartBody data: {
    data: HttpPart<bytes>;
  },
  @header contentType: "multipart/form-data",
): void;

✅ Correct

Section titled “✅ Correct”

Use the BYOS pattern where the client provides a storage location, instead of directly accepting binary data in the request body.

op download(): {
  data: bytes;
  @header contentType: "application/octet-stream";
};

Suppression

Section titled “Suppression”

Suppress when direct upload/download is appropriate for the API; otherwise use a storage account for large artifacts.