This API call is designed to create a Source in a PAA Group and deploy it to the PAAs of the group.
Rules
- Do not send `sourceId`. The API generates it, and returns `400` when the body has a `sourceId`.
- `paaGroupId` is optional. If you send it, it must be equal to the `paaGroupId` path parameter.
- `name` must be unique in the PAA Group.
- `translator.type` selects the data source type and the adapter. See `PaaSourceTranslator` for the supported values. An unknown value gives `404`.
- `paasProperties` is required. Send one item for each PAA that connects to the data source. Each `paaId` must be a PAA of this PAA Group.
- In each model, set `type` to `PHYSICAL`. Do not send `modelId`, `sourceIds` or `paaGroupId`; the API sets them.
- The API ignores `adapter` and `status`. A new Source always has the status `ACTIVE`.
- The API deploys the Source to each PAA in `paasProperties`. If the deployment fails on all of these PAAs, the API returns `400` and does not create the Source.
Notice
Accessing the API call is through a dedicated domain/URL, according to your PlainID Tenant LocationUsing HTML Encoded Special Characters
Use HTML encoded patterns when working with values that contain special characters like spaces, dashes, etc. Refer to this HTML URL Encoding Reference for a full list.
Important note about headers
Refer to the headers below to modify your cURL sample. Check if the following headers are in the sample, if not, ensure you add it to your cURL sample before pasting into your API tool.
Headers
*Required| Header | Value | cURL Line |
|---|---|---|
| Accept | `application/json` | `-H "Accept:application/json"` |
| Content-Type | `application/json` | `-H "Content-Type:application/json"` |
cURL Sample Guidelines
In order for the relevant parameters to appear in the cURL sample, you can input the values in the interactive API console on the right. They will then appear in the cURL sample on the bottom of the page in the correct format.
For more details about Administration API Authentication, check out the Authentication APIs documentation
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer 123
The Environment ID (a UUID). You can find it in the Details tab of the Environment Settings. If your PAA is installed on the Tenant level, use - as the envId.
The PAA Group ID, as the List PAA Groups API returns it in id.
The new Source.
{
"paaGroupId": "paa1",
"adapter": "ws",
"name": "mockrest2",
"status": "ACTIVE",
"description": "",
"properties": {},
"translator": {
"name": "plainid-rest-iRo",
"type": "plainid-rest",
"properties": {
"supportsfilter": "true"
}
},
"models": [
{
"type": "PHYSICAL",
"paaGroupId": "paa1",
"visible": true,
"name": "mockrest",
"description": "",
"properties": {},
"metadata": [
{
"type": "DDL",
"text": "CREATE FOREIGN TABLE context ( \n \n uid string,\n\n name string options (nameinsource 'name'),\n\n city string options (nameinsource 'city'),\njwt string \n\n) OPTIONS (nameinsource '$.Users[*]', \"plainid:method\" 'GET', \"plainid:URI\" '/users/$(uid)', \"plainid:unwrap\" 'true');"
}
]
}
],
"paasProperties": [
{
"paaId": "PAA3QK1UON1BOXS",
"properties": {
"EndPoint": "https://api.your-company.com/endpoint",
"Password": null,
"SecurityType": "None"
}
}
]
}Do not send sourceId. The API returns 400 when the body has a sourceId. Keep the values in the patterns and the length limits of this schema. The API does not check all of them.
Optional. If you send it, it must be equal to the paaGroupId path parameter.
The Source name. It must be unique in the PAA Group. The PAA uses it as the data source name, so use letters, digits and the characters _ - / # . only.
The Source description.
The Teiid translator of the Source. type selects the data source type and the adapter (the connection type) of the Source. The adapter sets the keys of properties and of paasProperties[].properties:
type | Data source | Adapter |
|---|---|---|
jdbc-simple | Simple JDBC | jdbc |
mysql | MySQL | jdbc |
postgresql | PostgreSQL | jdbc |
sqlserver | Microsoft SQL Server | jdbc |
oracle | Oracle | jdbc |
db2 | IBM DB2 | jdbc |
sybase | Sybase | jdbc |
ldap | LDAP | ldap |
mongodb | MongoDB | mongodb |
plainid-mongodb | MongoDB (new) | plainid-mongodb |
salesforce-41 | Salesforce (API 41.0) | salesforce |
odata4 | OData v4.0 | ws |
plainid-rest | REST | ws |
plainid-scim | SCIM | ws |
plainid-azure | Azure Active Directory | ws |
The translator type. The API compares it without case sensitivity. An unknown value gives 404.
The name of the translator instance. When name is empty or omitted, the API uses the value of type. When you also send properties, the API makes a unique name in the form <type>-<3 letters>, for example plainid-rest-iRo.
Translator override properties (Teiid translator settings), for example supportsfilter. All values are strings.
Source-level connection properties. The keys depend on the adapter of the Source, and the adapter depends on translator.type (see PaaSourceTranslator). The values are strings, numbers or booleans. Keys that are specific to one PAA go in paasProperties[].properties.
The models (schemas) of the Source. Set type to PHYSICAL and do not send modelId.
Always send PHYSICAL. The models of a Source are physical models. The API rejects a Source model without type.
Update Source only. Send the modelId of an existing model to update that model. Omit it to create a new model. Do not send it in the Create Source API.
When false, clients cannot query the model directly. Views can still use it.
The model name (the schema name in the PAA). Use letters, digits and the characters `_ - /
The model description.
Model properties. The values are strings, numbers or booleans.
The model definition, usually one DDL item with the CREATE FOREIGN TABLE statements.
The Teiid metadata type of text. Use DDL (Teiid DDL, for example CREATE FOREIGN TABLE or CREATE VIEW).
The PAA that this metadata applies to. Omit it for metadata that applies to all of the PAAs in the group.
The metadata text, for example a Teiid DDL statement.
The API ignores this value and sets it.
The API ignores this value and sets it.
The connection properties for each PAA. Send one item for each PAA that connects to the data source. The API deploys the Source to these PAAs.
The PAA ID. The PAA must be in the PAA Group. You can find the PAA ID in the Environment or Tenant Settings, in the Policy Authorization Agent section, or in the List PAA Groups API (detailed=true).
Update Source only, optional. The id that the Get Source by ID API returns for this PAA. Do not send it in the Create Source API.
Update Source only, optional. Do not send it in the Create Source API.
Connection properties for one PAA. The keys depend on the adapter of the Source, and the adapter depends on translator.type (see PaaSourceTranslator). The values are strings, numbers or booleans.Password: responses return null for a stored password, except for a secret reference in the form [NAME] or {{NAME}}, which the API returns as is. On update, send null (or omit the key) to keep the stored password of that PAA.
The API ignores this value. It sets the adapter from translator.type.
The API ignores this value. A new Source has the status ACTIVE.
Source Created
{
"data": {
"sourceId": "PIPS4BRPBO81AVPC",
"paaGroupId": "paa1",
"adapter": "ws",
"name": "mockrest2",
"status": "ACTIVE",
"description": "",
"properties": {},
"translator": {
"name": "plainid-rest-iRo",
"type": "plainid-rest",
"properties": {
"supportsfilter": "true"
}
},
"models": [
{
"type": "PHYSICAL",
"modelId": "PIPMM4BRPBO9U88OW",
"paaGroupId": "paa1",
"visible": true,
"name": "mockrest2",
"description": "",
"sourceIds": [
"PIPS4BRPBO81AVPC"
],
"properties": {},
"metadata": [
{
"type": "DDL",
"text": "CREATE FOREIGN TABLE context ( \n \n uid string,\n\n name string options (nameinsource 'name'),\n\n city string options (nameinsource 'city'),\njwt string \n\n) OPTIONS (nameinsource '$.Users[*]', \"plainid:method\" 'GET', \"plainid:URI\" '/users/$(uid)', \"plainid:unwrap\" 'true');"
}
]
}
],
"paasProperties": [
{
"id": "PIMR4BRPBOE7JUGW",
"sourceId": "PIPS4BRPBO81AVPC",
"paaId": "PAA3QK1UON1BOXS",
"properties": {
"EndPoint": "https://api.your-company.com/endpoint",
"Password": null,
"SecurityType": "None"
}
}
]
}
}The Source ID.
The PAA Group ID.
The adapter (connection type) of the Source, for example jdbc or ws. The API sets it from translator.type (see PaaSourceTranslator).
The Source name. It is unique in the PAA Group.
The status of the Source. The API sets it; it ignores this value in requests. A Source that you create or update with the API has the status ACTIVE.
The Source description.
Source-level connection properties. The keys depend on the adapter of the Source, and the adapter depends on translator.type (see PaaSourceTranslator). The values are strings, numbers or booleans. Keys that are specific to one PAA go in paasProperties[].properties.
The Teiid translator of the Source. type selects the data source type and the adapter (the connection type) of the Source. The adapter sets the keys of properties and of paasProperties[].properties:
type | Data source | Adapter |
|---|---|---|
jdbc-simple | Simple JDBC | jdbc |
mysql | MySQL | jdbc |
postgresql | PostgreSQL | jdbc |
sqlserver | Microsoft SQL Server | jdbc |
oracle | Oracle | jdbc |
db2 | IBM DB2 | jdbc |
sybase | Sybase | jdbc |
ldap | LDAP | ldap |
mongodb | MongoDB | mongodb |
plainid-mongodb | MongoDB (new) | plainid-mongodb |
salesforce-41 | Salesforce (API 41.0) | salesforce |
odata4 | OData v4.0 | ws |
plainid-rest | REST | ws |
plainid-scim | SCIM | ws |
plainid-azure | Azure Active Directory | ws |
The translator type. The API compares it without case sensitivity. An unknown value gives 404.
The name of the translator instance. When name is empty or omitted, the API uses the value of type. When you also send properties, the API makes a unique name in the form <type>-<3 letters>, for example plainid-rest-iRo.
Translator override properties (Teiid translator settings), for example supportsfilter. All values are strings.
The model type. The models of a Source are PHYSICAL.
The model ID.
The PAA Group ID.
When false, clients cannot query the model directly. Views can still use it.
The model name (the schema name in the PAA).
The model description.
The ID of the Source of the model.
Model properties. The values are strings, numbers or booleans.
The model definition, usually one DDL item with the CREATE FOREIGN TABLE statements.
The Teiid metadata type of text. Use DDL (Teiid DDL, for example CREATE FOREIGN TABLE or CREATE VIEW).
The PAA that this metadata applies to. Omit it for metadata that applies to all of the PAAs in the group.
The metadata text, for example a Teiid DDL statement.
The connection properties for each PAA of the Source.
The ID of this set of PAA connection properties.
The Source ID.
The PAA ID.
Connection properties for one PAA. The keys depend on the adapter of the Source, and the adapter depends on translator.type (see PaaSourceTranslator). The values are strings, numbers or booleans.Password: responses return null for a stored password, except for a secret reference in the form [NAME] or {{NAME}}, which the API returns as is. On update, send null (or omit the key) to keep the stored password of that PAA.
Bad Request. The request is not valid, or the PAAs could not deploy the change.
{
"errors": [
{
"code": "PIP-019",
"id": "EQ7CMX",
"status": 400,
"name": "BaseError",
"message": "Source with name mockrest already exists"
}
]
}{
"errors": [
{
"code": "",
"id": "EQ7CMX",
"status": 400,
"name": "BadRequestError",
"message": "sourceId must be null"
}
]
}{
"errors": [
{
"code": "",
"id": "EQ7CMX",
"status": 400,
"name": "BaseError",
"message": "paaId: PAA3QK1UON1BOXS is not belong to paaGroupId: PAG1WMX530NXUKG"
}
]
}{
"errors": [
{
"code": "",
"id": "EQ7CMX",
"status": 400,
"name": "BadRequestError",
"message": "Metadata count mismatch"
}
]
}The bearer token or the Client ID and Client Secret are missing or not valid.
Missing or invalid bearer token
{
"message": "Invalid or missing authentication token"
}The error returned by AuthZen endpoints, with a single message describing what went wrong. AuthZen endpoints use this format instead of the errors array returned by other Runtime APIs.
The error message
Forbidden. The access token does not have the permission for this operation on the Environment (or on the Tenant, when envId is -).
Not Found. The Environment, the PAA Group, the Source, the Views or the translator type does not exist.
{
"errors": [
{
"code": "HBC-021",
"id": "EQ7CMX",
"status": 404,
"name": "PaaGroupNotFoundError",
"message": "PAA Group does not exist"
}
]
}{
"errors": [
{
"code": "APIV-022",
"id": "EQ7CMX",
"status": 404,
"name": "EnvironmentNotExistError",
"message": "Environment ID: [not-a-uuid] does not exist"
}
]
}{
"errors": [
{
"code": "",
"id": "EQ7CMX",
"status": 404,
"name": "NotFoundError",
"message": "source not found"
}
]
}An internal error occurred, or a dependency such as the cache or an Identity Source failed while processing the request.
Cache unavailable
{
"message": "Unable to connect to Redis cache service"
}Identity Source unavailable
{
"message": "PIP unreachable"
}Internal error
{
"message": "Internal error while evaluating the request"
}The error returned by AuthZen endpoints, with a single message describing what went wrong. AuthZen endpoints use this format instead of the errors array returned by other Runtime APIs.
The error message