Version 23.0.9145

• Define a Master Connection
• Register User Connections
• Templated Connections
  • .NET
    • Example .NET Connection String
  • Cross-Platform
    • Example Cross-Platform Connection String

By default, a connection configured in API Server is used by all users. In some cases you might want each user to have their own connection to the underlying database or source. This is typically done to leverage the access control configured on the back-end server.

API Server supports user-specific connections. When this feature is enabled, only the administrator can use this connection to retrieve metadata from the data source. API Server expects each user to have their own connection. If a user has not defined a connection, they are prompted to do so before any calls to the API can succeed.

Define a Master Connection

When creating connections, API Server administrators can set a connection as a master connection. The administrator can import resources and actions to this connection in the same way as standard connections. However, a user who has not registered their individual connection receives an error when querying those resources.

Register User Connections

Users must register an individual connection to access the resources corresponding to the master connection. A registration URL is generated for each master connection, where users can log in with their credentials:

http://MyServer:MyPort/registerUserConnection.rst?conn=my_master_connection

On this page, users can establish a connection by providing the information required by the data source. After saving the connection, users can query resources exposed by API Server. API Server maps the resource to the individual connection created by the user.

Note: Users require POST permissions to register their connection.

Templated Connections

The API Server administrator can control which connection properties the user can configure. This is done by templating the connection with predefined properties and providing a placeholder for properties that the user should configure. To specify a template, add a connection string in your settings.cfg file, in the UserConnectionTemplates section. Include the fixed properties and indicate which properties can be defined by users with a question mark ?. The format of this connection string must match the platform and specification of the driver.

.NET

For API Server versions 2021 and later, the settings.cfg file is located in C:\ProgramData\CData\apiserver\.

Versions 2020 and earlier stored settings.cfg in the app_data subfolder of the application root. Installations that were upgraded from versions prior to 2021 still use this location. By default, this is C:\Program Files\CData\CData API Server\www\app_data\.

Example .NET Connection String

[UserConnectionTemplates]
MyMasterSQLConnection = "Data Source=localhost;Initial Catalog=Northwind;User ID=?;Password=?;"

Cross-Platform

In the Cross-Platform edition, settings.cfg is in the data directory. In Windows, this is located in C:\ProgramData\CData\; in Unix and Mac, it is located in ~/cdata.

Example Cross-Platform Connection String

[UserConnectionTemplates]
MyMasterSQLConnection = "jdbc:sqlserver://localhost:1433;Database=Northwind;user=?;password=?;"