Skip to content

You are viewing documentation for Immuta version 2.8.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

Immuta Custom Blob Handler

Audience: Data Owners

Content Summary: A blob is any blob of data representation from your database, API, filesystem, etc. A blob store handler is how Immuta reaches back to a remote database to bring back blobs. Blob store handlers are exposed as REST web services defined by the Data Owner. To return blobs, these services expect a blob ID in the request.

This page details how to create, deploy, and secure custom blob handlers.

Creating a Custom Blob Handler

  1. Expose your own REST web service that responds with a blob with the following RESTful structure:


    where uniqueid is the blob ID that Immuta is requesting via an HTTPS GET request.

    For example, you could register this blob store handler as part of the create data source workflow by selecting custom and entering this URL:

    Immuta calls this URL when requesting blob id 1:

  2. Post metadata to Immuta via the POST /dataSource/{dataSourceId}/blobs endpoint (described below) to inform the platform of the possible blob IDs. For example, in the scenario above the ID is 1.

Passing Metadata to Immuta

After you create a blob store handler, you must pass Immuta metadata about your blobs/entities. This can be done through the POST /dataSource/{dataSourceId}/blobs endpoint.

post_blobs_body {
    blobId (string): The unique ID used to identify this Blob within its DataSource,
    filename (string, optional): The value that will display in the file system,
    tags (array[string], optional): A list of all tags associated with this Blob.,
    features (array[object], optional): A list of all features associated with this Blob.,
    visibility (post_blobs_body_visibility),
    date (string): A datetime which corresponds to a date within the record itself.,
    filesize (integer, optional): The size of the file in bytes.

Deploying a Custom Blob Handler

Handlers are not hosted within the Immuta product, so it is up to the creator of the handler to deploy and maintain handlers.

Securing a Custom Blob Handler

When registering a blob store handler, the Data Owner is provided with these security options:

  • The blob store can be accessed over SSL for added security when data is moving across the network.
  • The Data Owner may provide a CA bundle for their blob store handler in the event that an internally signed or self-signed certificate is being used by the blob store handler endpoint.
  • The Data Owner can go one step further and provide a client certificate and key, which will be used by Immuta when contacting the blob store handler. This will enable two-way SSL with client verification (if that method of operation is supported by the blob store handler endpoint).

The two-way SSL configuration is highly recommended as it is the most secure configuration for a custom blob store handler endpoint.

Avoiding Load on Database

Immuta does aggressive caching to avoid having to hit your blob store handler multiple times. Even with this precaution, if load is still a concern, consider doing some additional caching in your blob store handler.