Create Connection

Overview

Creates a new connection in a project. Connections are reusable configurations for external systems such as databases, message queues, email servers, and logging systems.

Endpoint

POST /apiops/projects/{projectName}/connections/{connectionName}/

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header Value Required
Authorization Bearer {token} Yes
Content-Type application/json Yes

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
connectionName string Yes Connection name (must match name in body)

Request Body

Note: The API uses DTOs (Data Transfer Objects) for requests and responses. The type field is used as the discriminator field to identify the connection type, replacing the previous _class field used in internal entity models.

Full JSON Body Example (Email Connection)

{
  "type": "email",
  "name": "my-email-connection",
  "description": "Email connection for sending notifications",
  "deployToWorker": true,
  "enabled": true,
  "host": "smtp.gmail.com",
  "port": 587,
  "enableStartTls": true,
  "auth": true,
  "username": "user@example.com",
  "password": "app-password",
  "defaultEncoding": "UTF-8",
  "addressToTest": "test@example.com",
  "from": "noreply@example.com",
  "additionalProperties": []
}

Request Body Fields

Common Fields (All Connection Types)
Field Type Required Default Description
type string Yes - Connection type discriminator field. Used to identify the connection type in API requests/responses. Valid values: email, kafka, elasticsearch, database, ldap, ftp, rabbitMq, activeMq, snmp, linux-script, graylog, syslog, webhook, logback
name string Yes - Connection name (must match path parameter)
description string No - Connection description
deployToWorker boolean No true Whether to deploy to worker
enabled boolean No true Whether connection is enabled

Connection Types

  • email - Email (SMTP) connection
  • kafka - Kafka connection
  • elasticsearch - Elasticsearch connection
  • database - Database connection
  • ldap - LDAP connection
  • ftp - FTP connection
  • rabbitMq - RabbitMQ connection
  • activeMq - Apache ActiveMQ connection
  • snmp - SNMP connection
  • linux-script - Linux Script connection
  • ops-genie - OpsGenie connection (if available)
  • graylog - Graylog connection
  • syslog - Syslog connection
  • webhook - Webhook connection
  • logback - Logback connection

Note: Connection-specific fields vary by connection type. See individual connection type documentation for complete field descriptions:

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true
  }
}

Response Fields

Field Type Description
success boolean Indicates if the request was successful
deploymentResult object Deployment result (if deployToWorker=true)
deploymentResult.success boolean Deployment success

Error Response (400 Bad Request)

{
  "error": "bad_request",
  "error_description": "Connection (name: my-email-connection) already exists!"
}

Common Causes

  • Connection name already exists
  • Connection name in path does not match name in body
  • Invalid connection type
  • Missing required fields for connection type
  • Invalid field values

Error Response (401 Unauthorized)

{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}

Error Response (404 Not Found)

{
  "error": "not_found",
  "error_description": "Project 'MyProject' not found"
}

cURL Example

Example 1: Create Email Connection

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-email-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "name": "my-email-connection",
    "description": "Email connection for sending notifications",
    "deployToWorker": true,
    "enabled": true,
    "host": "smtp.gmail.com",
    "port": 587,
    "enableStartTls": true,
    "auth": true,
    "username": "user@example.com",
    "password": "app-password",
    "defaultEncoding": "UTF-8",
    "from": "noreply@example.com"
  }'

Example 2: Create Database Connection

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-db-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "database",
    "name": "my-db-connection",
    "description": "PostgreSQL database connection",
    "deployToWorker": true,
    "enabled": true,
    "host": "localhost",
    "port": 5432,
    "databaseName": "mydb",
    "username": "dbuser",
    "password": "dbpassword",
    "driverClassName": "org.postgresql.Driver",
    "jdbcUrl": "jdbc:postgresql://localhost:5432/mydb"
  }'

Example 3: Create Kafka Connection

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-kafka-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kafka",
    "name": "my-kafka-connection",
    "description": "Kafka connection for event streaming",
    "deployToWorker": true,
    "enabled": true,
    "topicName": "events",
    "bootstrapServers": "localhost:9092",
    "keyStoreName": "my-keystore",
    "trustStoreName": "my-truststore"
  }'

Notes and Warnings

  • Name Matching: Connection name in path parameter must match the name field in the request body (case-insensitive)
  • Unique Names: Connection names must be unique within a project
  • Secret Fields: Never commit connection configurations with secrets to version control
  • Connection Types: Each connection type has different required fields. See individual connection type documentation for details
  • Deployment: If deployToWorker: true, connection is automatically deployed to workers
  • References: Some connection types support references to certificates or keystores by name (e.g., keyStoreName, trustStoreName)