By default, a standard connection configured in the API Server is used by all users. In some cases it is useful for 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.

The API Server supports user-specific connections. When this feature is enabled, only the administrator may use this connection to retrieve metadata from the data source. The API Server then expects each user to have their own connection defined. 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 a connection, the API Server admin can choose to set a connection as a master connection. The admin may import resources and actions similarly to standard connections. However, a user who has not first registered their individual connection will be met with an error when querying those resources.

Register User Connections

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

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

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

Note: A user requires the POST permissions in order to register their connection.

Templated Connections

The API Server admin can control which connection properties are configurable by the user. This is done by templating the connection with predefined properties and providing a placeholder for properties that should be configured by the user. To specify such a template, add a connection string in your settings.cfg, under the UserConnectionTemplates section. In this connection string, include the fixed properties and indicate which properties can be defined by users with ‘?’. The format of this connection string should match the platform and specification of the driver.

.NET

Starting with the 2021 version of the CData API Server, the settings.cfg file is located in C:\ProgramData\CData\apiserver\.

Versions 2020 and earlier stored the settings.cfg file 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\.

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

Java

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

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