Feature Request: Support for Non-UTF8 Encoded Files with "externalValue"

[Apoorva64]

Problem Statement

Currently, Microcks does not support mocking of non-UTF8 encoded data, such as binary files, PDFs, images, etc. This limitation restricts the ability to fully test APIs that are expected to handle various file types in real-world scenarios.

Proposed Feature

The proposed enhancement aims to extend Microcks' functionality to include support for non-UTF8 encoded data by utilizing the "externalValue" property defined in the OpenAPI specification (https://swagger.io/specification/#example-object). This feature would enable Microcks to reference and serve external files, such as binary files, PDFs, images, and more, as part of API mocking responses.

Use Cases

• Testing file download APIs that return PDFs, images, or other binary files.
• Simulating file uploads to ensure APIs correctly handle binary data.
• Validating API behavior when serving different file types and content, including multimedia and document formats.
• Ensuring that APIs can handle various content types in a robust and performant manner.

Benefits

• Enhanced testing capabilities for APIs that interact with binary data.
• Improved development workflows by allowing thorough testing before integration with actual services.
• Increased confidence in API reliability and performance when dealing with non-textual data.

Implementation

1. Relative "External Value" Support

The first step in implementing this feature is to enable support for relative file references using the "externalValue" property. This would allow users to specify file paths relative to the location of the API specification. Microcks will:

• resolve these relative paths
• fetch the file and store it as a ressource
• return the appropriate file content as mock responses when called.

2. URL "External Value" Support

Building upon the initial support for relative file references, the next phase involves enabling Microcks to handle "externalValue" properties with full URLs. This capability will allow Microcks to fetch and serve files from remote locations. For secure access to these resources, Microcks will utilize its existing credential handling mechanism. Users will simply need to reference the appropriate credential object within their API specification using extensions ("x-microcks-example")

[Apoorva64]

Implementation of Version 1 found at #1094

[lbroudoux]

Thank you, @Apoorva64, for taking the time to write this.

I've got some questions at first read:

• The mentioned use cases seem to be all related to mocking; what about contract-testing of such API expecting binary content as an input?
• Your proposition involves 2 different mechanisms: Microcks stores the file, and Microcks acts as a proxy. If I remember correctly, this is not how we deal with $ref as we store everything to eliminate the risks of stale dependencies. What could be the reason to do things differently here? I can think about the volume of files mainly, but it'd be great to have a clear justification
• For all the dependencies resolution ($ref), we are actually reusing the same secret as the one allowing access to the root resource. Why would you think this case need a different secret?

Thanks!

[Apoorva64]

@lbroudoux sorry for the late response

• I don't think that it will be possible to do contract testing on binary data as it has no schema the best we could do is check the Content-Type.
• The 2nd version does not include microcks being a proxy but includes that microcks should be able to fetch ressources that are somewhere else and then store it in microcks.
• Sometimes the data for the mocks is not in the same repository and may be in another one thus needing an another Secret.

[Apoorva64]

@lbroudoux -->?

[Apoorva64]

@lbroudoux Another way to do this is to use the base64 data URLs in the external value field to put the data directly in the OpenApi