REST API Reference

Back Next

connection

Use this resource to request connection details for an organization. You can also use this resource to create, update, test, and delete a connection.

Details GET Request

You can request the following details using a connection GET request:

Details of all connections in the organization.

Details for a particular connection in the organization.

List of objects that you can use as a source or target with a particular connection.

List of connections of a specified type associated with a Secure Agent or runtime environment.

Metadata details for a specified connection.

Do not use connections with names that begin with "DI Data Preview_".

Details of all connections in the organization: To request the details of all connections in the organization, use the following URI:
/api/v2/connection
Details of a particular connection: To request the details of a particular connection, include the connection ID or name in the URI. Use one of the following URIs:
/api/v2/connection/<id>

/api/v2/connection/name/<name>
If you use the connection name in the URI and the connection name includes a space, replace the space with
%20
. For example:
/api/v2/connection/name/my%20connection
List of objects that you can use as a source or target: You can request the objects that you can use as a source or target. To request source or target objects, you can include either the connection ID or connection name in the URI. Use one of the following URIs:
/api/v2/connection/source/<id>

/api/v2/connection/target/<id>

/api/v2/connection/source/name/<name>

/api/v2/connection/target/name/<name>
If you use the connection name in the URI and the connection name includes a space, replace the space with
%20
. For example:
/api/v2/connection/target/name/my%20connection; If you expect to receive a large number of objects, you might want to include one of the following parameters:
searchPattern. Use the searchPattern parameter to filter the results so that only the objects with the specified string in the object name are included in the response. To use the searchPattern parameter, use the following URI:
/api/v2/connection/<source or target>/<id>?searchPattern=<pattern>

For example, the following request returns source objects that include "abc" in the object name:
/api/v2/connection/source/002D420000000J?searchPattern=abc

maxRecordsCount. Use the maxRecordsCount parameter to set the maximum number of objects to return. To use the maxRecordsCount, use the following URI:
/api/v2/connection/<source or target>/<id>?maxRecordsCount=<max number of objects>

For example, the following request returns a maximum of 5000 source objects:
/api/v2/connection/source/002D420000000J?maxRecordsCount=5000

If you don't include the maxRecordsCount parameter, a maximum of 200 objects can be returned for the request.
List of connections of a specified type associated with a Secure Agent or runtime environment: To request a list of connections by Secure Agent ID and connection type, use the following URI:
/api/v2/connection/search?agentId=<agentId>&uiType=<uiType>; To request a list of connections by runtime environment ID and connection type, use the following URI:
/api/v2/connection/search?runtimeEnvironmentId=<runtimeEnvironmentId>&uiType=<uiType>; If you pass both agentId and runtimeEnvironmentId, the service uses runtimeEnvironmentId and ignores agentId. If you pass only agentId, the service translates agentId into its corresponding runtimeEnvironmentId before it saves the resource to the repository.
Metadata details for a specified connection: To request metadata details for a specified connection, use the following URI:
/api/v2/connection/source/<connection ID>/metadata

/api/v2/connection/target/<connection ID>/metadata
The metadata is returned in the runtimeAttribute object which contains the following attributes:
name
dataType
defaultValue
label
mandatory
maxLength
sessionVarAllowed
possibleValues

Use the following connection request URI attributes:

Field	Type	Required	Description
agentId	String	-	Secure Agent ID
runtimeEnvironmentId	String	-	Runtime environment ID.
uiType	String	Yes	Connection type. Use one of the following options: CSVFile. CSV flat file. FTP. MS_ACCESS. MSD. Microsoft Dynamics CRM. MySQL. ODBC. Oracle. OCOD. Oracle CRM On Demand. Salesforce. SFTP. Secure FTP. SAP_ALE_IDoc_Reader. SAP IDoc Reader. SAP_ALE_IDoc_Writer. SAP IDoc Writer. SqlServer. Microsoft SQL Server 2000. SqlServer2005. Microsoft SQL Server 2005. SqlServer2008. Microsoft SQL Server 2008. SqlServer2012. Microsoft SQL Server 2012. SqlServer2014. Microsoft SQL Server 2014. SqlServer2016. Microsoft SQL Server 2016. SqlServer2017. Microsoft SQL Server 2017. TOOLKIT. Informatica Cloud Connector. Also use for NetSuite connections. WebServicesConsumer. Web Service.

Details GET Response

Returns the connection object for the requested connection ID. If you request information for all connections in the organization, returns a connection object for each connection in the organization.

If you request a list of connections based on the runtime environment ID and connection type, returns a connection object for each connection that matches the requirements.

If you request a list of source or target objects available for the requested connection ID, returns the connListItem object for each available object.

Returns the error object if errors occur.

The connection object includes different information based on connection type.

The following table describes attributes included in a connection object:

Field	Type	Description
id	String	Connection ID.
orgId	String	Organization ID.
name	String	Connection name.
description	String	Description of the connection.
createTime	Date/time	Time the connection was created.
updateTime	Date/time	Last time the connection was updated.
createdBy	String	User who created the connection.
updatedBy	String	User who last updated the connection.
agentId	String	Secure Agent ID for Flat File, FTP/SFTP, Microsoft SQL Server, MS Access, MySQL, ODBC, Oracle, and Web Service connections.
runtimeEnvironmentId	String	Runtime environment used by the connection. This is the Runtime Environment field in the user interface. In the response returned to the user interface, this attribute is named agentGroupId.
instanceName	String	Microsoft SQL Server instance name.
host	String	Host name for FTP/SFTP, Microsoft SQL Server, MySQL, and Oracle connections.
domain	String	Domain name for Microsoft Dynamics CRM connections that use IFD or Active Directory authentication, and Web Service connections.
dateFormat		Date format for Flat File, FTP, and SFTP connections.
database	String	Returns the following information: For Microsoft SQL Server and MySQL connections, returns the database name. For Flat File connections, returns the directory. For FTP and SFTP connections, returns the local directory. For MS Access and ODBC connections, returns the data source name. For Oracle connections, returns the service name. For SAP IDoc Writer and Reader connections, returns the destination entry. For Web Service connections, returns the service URL.
codepage		Code page for Flat File, FTP, SFTP, Microsoft SQL Server, MySQL, MS Access, ODBC, Oracle, and SAP.
clientCode	String	Client code for SAP IDoc Writer connections.
authenticationType	String	Authentication type for Microsoft Dynamics CRM, Microsoft SQL Server, and Web Service connections.
adjustedJdbcHostName	String	Host name. Or host and instance name for Microsoft SQL Server connections.
accountNumber	String	Account ID for NetSuite connections.
languageCode	String	Language code for SAP IDoc Writer connections.
remoteDirectory	String	Remote directory for FTP/SFTP connections.
schema	String	Schema name for Microsoft SQL Server, ODBC, Oracle, and Web Service connections.
serviceUrl	String	Service URL for Microsoft Dynamics CRM, Oracle CRM On Demand, and Salesforce connections.
shortDescription	String	The first 50 letters of the description.
type	String	Connection type returns one of the following responses: CSVFile. CSV flat file. FTP. MS_ACCESS. MSD. Microsoft Dynamics CRM. MySQL. ODBC. Oracle. OCOD. Oracle CRM On Demand. Salesforce. SFTP. Secure FTP. SAP_ALE_IDoc_Reader. SAP IDoc Reader. SAP_ALE_IDoc_Writer. SAP IDoc Writer. SqlServer. Microsoft SQL Server 2000. SqlServer2005. Microsoft SQL Server 2005. SqlServer2008. Microsoft SQL Server 2008. SqlServer2012. Microsoft SQL Server 2012. SqlServer2014. Microsoft SQL Server 2014. SqlServer2016. Microsoft SQL Server 2016. TOOLKIT. Informatica Cloud Connector. WebServicesConsumer. Web Service. The user interface field name on the Connections page varies depending on the connection. For example, for SQL Server, the user interface field name is SQL Server Version. Also note that for SQL Server, the REST API attribute that populates the value in the user interface is named subType.
port	Int	Port number for FTP/SFTP, Microsoft SQL Server, MySQL, and Oracle connections.
password	String	Password for the connection.
username	String	User name for the connection.
securityToken	String	Security token for a Salesforce connection.
stsUrl	String	Security token service URL for Microsoft Dynamics CRM connections that use Active Directory authentication.
organizationName	String	Organization name for Microsoft Dynamics CRM connections.
timeout	Int	Timeout for Web Service connections.
trustCertificatesFile	String	Trust certificates file name for Web Service connections.
certificateFile	String	Certificates file name for Web Service connections.
certificateFilePassword	String	Certificates file password for Web Service connections.
certificateFileType	String	Certificates file type for Web Service connections.
privateKeyFile	String	Private key file name for Web Service connections.
privateKeyPassword	String	Private key password for Web Service connections.
privateKeyFileType	String	Private key file type for Web Service connections.
connParams	String	Parameters used in the connection. Includes connection attributes in the connParam object for SAP, NetSuite, Oracle CRM On Demand, ODBC, or other Informatica Cloud connectors.
federatedId	String	Global unique identifier for the connection.
internal	Boolean	Indicates whether the connection was created internally for data preview purposes only.
retryNetworkError	Boolean	Used for internal purposes only.
supportsCCIMultiGroup	Boolean	Used for internal purposes only.
connListItem		List of connections included in the connListItem object.
id	String	Included in the connListItem object. Source or target ID.
name	String	Included in the connListItem object. Source or target name.

Test GET Request

To test a connection, use the connection ID in the following URI:

/api/v2/connection/test/<id>

Test GET Response

Returns the success object if the test succeeds.

Returns the error object if errors occur.

POST Request

You can create or update connections. To update a connection, use the connection ID with the following URI. To create a connection, omit the optional connection ID.

/api/v2/connection/<id>

You can submit a partial update using partial mode. To submit a request using partial mode, use a JSON request and include the following line in the header:

Update-Mode=PARTIAL

In a connection POST request, use the additional attributes in the connection object. The attributes used by Informatica Cloud Connector connections vary by connection type.

To create or update an Informatica Cloud Connector connection, consult the Informatica Cloud application for the attributes used by the connection. Enclose any attributes that are not listed in the following tables in a connParam object.

To get a list of connectors that are available to the organization and attribute information for a specific connector type, see connector.

For more information about attributes and data types used for creating connections through the REST API, see Connection user interface fields to REST API attributes mapping and Connector data types.

POST Response

If successful, returns the connection object for the connection that was created or updated.

Returns the error object if errors occur.

DELETE Request

To delete a connection, use the connection ID in the following URI.

/api/v2/connection/<id>

DELETE Response

Returns the 200 response code if the request is successful.

Returns the error object if errors occur.

POST Example

To update an SAP Table connection, you might use the following request, enclosing SAP attributes in the connParam object:

POST <serverUrl>/api/v2/connection/0002D420000000J
Content-Type: application/xml
Accept: application/xml
icSessionId: <icSessionId>

<connection>
  <id>0002D420000000J</id>
  <orgId>00342000</orgId>
  <name>test dir</name>
  <type>TOOLKIT</type>
  <agentId>00001Y08000000000002</agentId>
  <username>username</username>
  <password>password</password>
  <instanceName>SAPTableConnector</instanceName>
  <connParams>
     <agentId>00001Y08000000000002</agentId>
     <username>username</username>
     <password>password</password>
     <client>800</client>
     <language>EN</language>
     <Saprfc Ini Path>C:\\Windows\\SysWOW64</Saprfc Ini Path>
     <Destination>GE6</Destination>
  </connParams>
  <runtimeEnvironmentId>00000C25000000000002</runtimeEnvironmentId>
</connection>

A successful request returns the connection object that you updated.

Data Integration REST API

CSV Flat File Connections

FTP and SFTP Connections

Microsoft Access Connections

Microsoft Dynamics CRM Connections

Microsoft SQL Server Connections

Oracle CRM On Demand Connections