{"id":16783,"date":"2024-01-02T01:22:39","date_gmt":"2024-01-02T06:22:39","guid":{"rendered":"https:\/\/www.iri.com\/blog\/?p=16783"},"modified":"2025-09-15T08:35:57","modified_gmt":"2025-09-15T12:35:57","slug":"iri-darkshield-rdb-rpc-api","status":"publish","type":"post","link":"https:\/\/www.iri.com\/blog\/data-protection\/iri-darkshield-rdb-rpc-api\/","title":{"rendered":"IRI DarkShield-RDB RPC API"},"content":{"rendered":"

IRI DarkShield<\/span><\/a> Version 5 includes a Remote Procedure Call (RPC) Application Programming Interface (API) for searching and masking data stored in relational databases. Note that DarkShield also features a fit-for-purpose job wizard in IRI Workbench for databases, which can be an alternative to RDB data discovery and masking in IRI FieldShield for certain use cases<\/a>.\u00a0<\/span><\/p>\n

Editors Note<\/strong>: DarkShield Version 6 also includes a single-endpoint REST API<\/a> that covers RDB, NoSQL DB, files, and streaming text sources.<\/em><\/p>\n

This API can be used within applications you write, or directly from <\/span>IRI Workbench<\/span><\/a> jobs you configure graphically. Outside Workbench, you can embed the API as middleware in a (e.g. CI\/CD) pipeline. Within Workbench, you can specify and export its search and mask contexts through the <\/span>New Relational DB Search\/Masking Job<\/span><\/i> wizard.<\/span><\/p>\n

The DarkShield-RDB API can support any relational database for which a JDBC driver is provided. It is built as a plugin atop the IRI Web Services Platform (codenamed Plankton), which allows you to pick which services you require while utilizing the same hosting, configuration, and logging capabilities provided through the platform.<\/span><\/p>\n

\"\"<\/p>\n

Before continuing with this article, please familiarize yourself with the operations of the DarkShield-<\/span>Files<\/span><\/i> API in <\/span>this article<\/span><\/a> and the <\/span>base <\/span><\/i>DarkShield API in <\/span>this article<\/span><\/a>.<\/span><\/p>\n

The DarkShield-<\/span>RDB<\/span><\/i> API utilizes the DarkShield-<\/span>Files<\/span><\/i> API to handle binary data, and the <\/span>base <\/span><\/i>DarkShield API to handle non-binary values extracted from columns in tables.<\/span><\/p>\n

\"\"<\/p>\n

All demos associated with this article can be downloaded from our Git repository <\/span>here<\/span><\/a>. To run the demos, you will need a working copy of the DarkShield-RDB API hosted locally on your computer. Contact your <\/span>IRI representative<\/span><\/a> for a trial copy of the software.<\/span><\/p>\n

RDB Search Contexts<\/b><\/h5>\n

The RDB API introduces an extension to the File Search Context, an RDB Search Context<\/span>,<\/span><\/i> for defining search criteria for a relational database. The following snippet of the OpenAPI definition shows the structure of its schema:<\/span><\/p>\n

\"\"<\/p>\n

The RDB Search Context uses a <\/span>name <\/span><\/i>attribute to uniquely identify a context for performing search operations. The <\/span>fileSearchContextName<\/span><\/i> attribute indicates a File Search Context that will be associated with the RDB Search Context. There is also a <\/span>configs <\/span><\/i>attribute used to pass parameters related to connecting and interacting with a relational database.<\/span><\/p>\n

RDB Mask Contexts<\/b><\/h5>\n

The RDB API introduces an extension to the File Mask Context, an RDB Mask Context, for defining search criteria for a relational database. The following snippet of the OpenAPI definition shows the structure of its schema:<\/span><\/p>\n

\"\"<\/p>\n

The RDB Mask Context <\/span>name <\/span><\/i>attribute uniquely identifies the context when performing masking operations. The <\/span>fileMaskContextName<\/span><\/i> attribute indicates the File Mask Context that will be associated with the RDB Mask Context. There is also a <\/span>configs <\/span><\/i>attribute used to pass parameters for connecting and interacting with a relational database.<\/span><\/p>\n

RDB Search Configs<\/b><\/h5>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
<\/td>\nKey Name<\/strong><\/td>\nDescription<\/strong><\/td>\nOptional or Required<\/strong><\/td>\n<\/tr>\n
Schema<\/span><\/td>\nschemaName<\/span><\/td>\nThe name of the schema.<\/span><\/td>\nRequired<\/span><\/td>\n<\/tr>\n
URL<\/span><\/td>\nurl<\/span><\/td>\nURL for JDBC connection.<\/span><\/td>\nRequired<\/span><\/td>\n<\/tr>\n
User<\/span><\/td>\nusername<\/span><\/td>\nThe username.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Password<\/span><\/td>\npassword<\/span><\/td>\nThe password.<\/span><\/td>\nOptional: if authenticating password is required.<\/span><\/td>\n<\/tr>\n
Regex Include\u00a0<\/span><\/td>\nincludePattern<\/span><\/td>\nOnly tables that match based off of a Java regex pattern inside a schema will be searched.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Regex Exclude\u00a0<\/span><\/td>\nexcludePattern<\/span><\/td>\nTables that do not match based off of a Java regex pattern inside a schema will be searched.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Fetch Size<\/span><\/td>\nfetchSize<\/span><\/td>\nDictates how many rows to handle per batch. Default value is 1024. Expects an integer.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Driver Configurations<\/span><\/td>\ndriverConfigs<\/span><\/td>\nAdditional JDBC driver options. Key Value pairs with string values expected.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Driver Class<\/span><\/td>\ndriverClassName<\/span><\/td>\nClass name of the JDBC driver to be loaded.<\/span><\/td>\nOptional: JDBC driver will attempt to be loaded based on the URL specified.<\/span><\/td>\n<\/tr>\n
Row Limit<\/span><\/td>\nrowLimit<\/span><\/td>\nMax number of rows to be processed in a source table.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Data Types<\/span><\/td>\ndataTypes<\/span><\/td>\nList of possible data types to include in search:<\/span> [ varchar, char, blob, numeric, integer, float, date, time, timestamp, real, longvarchar, longvarbinary, longnvarchar, binary, varbinary, clob, nclob, sqlxml, nvarchar, nchar, tinyint, smallint, bigint, double, decimal, time_with_timezone, timestamp_with_timezone, struct, ref, array, bit, rowid, ref_cursor, other, , java_object, distinct, datalink, boolean ]<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
RDB Mask Configs<\/b><\/h5>\n\n\n\n\n\n\n\n\n\n\n
<\/td>\nKey Name<\/strong><\/td>\nDescription<\/strong><\/td>\nOptional or Required<\/strong><\/td>\n<\/tr>\n
Schema<\/span><\/td>\nschemaName<\/span><\/td>\nThe name of the schema.<\/span><\/td>\nRequired<\/span><\/td>\n<\/tr>\n
URL<\/span><\/td>\nurl<\/span><\/td>\nURL for JDBC connection.<\/span><\/td>\nRequired<\/span><\/td>\n<\/tr>\n
User<\/span><\/td>\nusername<\/span><\/td>\nThe username.<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Password<\/span><\/td>\npassword<\/span><\/td>\nThe password.<\/span><\/td>\nOptional: if authenticating password is required.<\/span><\/td>\n<\/tr>\n
Driver Configurations<\/span><\/td>\ndriverConfigs<\/span><\/td>\nAdditional JDBC driver options<\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n
Driver Class<\/span><\/td>\ndriverClassName<\/span><\/td>\nClass name of the JDBC driver to be loaded.<\/span><\/td>\nOptional: JDBC driver will attempt to be loaded based on the URL specified.<\/span><\/td>\n<\/tr>\n
Disable Foreign Keys<\/span><\/td>\ndisableForeignKeys<\/span><\/td>\nAttempt to automatically disable foreign keys in target tables when masking.<\/span> <\/span>1<\/sup><\/a><\/span><\/span><\/td>\nOptional<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
DarkShield-RDB API Endpoints<\/b><\/h5>\n

\"\"<\/p>\n

The RDB API is an extension of the Files API, which is an extension of the DarkShield base API. As such the RDB API requires not only RDB Search\/Mask Contexts, but File Search\/Mask Contexts and base API Search\/Mask Contexts to be created via their respective endpoints.<\/span><\/p>\n

A breakdown of API endpoint calls is as follows:<\/span><\/p>\n