# Is Valid Connection String API

> Test a database connection string before saving it with the is valid connection string system API of API Maker - MongoDB, MySQL, MariaDB, SQL Server, PostgreSQL and Oracle - the check behind the Test Instance button.

Source: https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-is-valid-connection-string-api.html

Opens a connection with the string given and closes it : the check the **Test Instance** button of the instances page makes. Useful for an onboarding screen which lets a customer register their own database, or before writing a tenant row.

| | |
|---|---|
| Method | POST |
| URL | `/api/system-api/admin/is-valid-connection-string` : `admin` is the user path of your account |
| Body | `{ connectionString, instanceType, oracleDBUsername?, oracleDBPassword?, oracleDBPrivilege? }` or an array of them |
| Answer | `data` : `{ success, data: true | false, error? }`, or an array of them |
| From code | [`g.sys.system.isValidConnectionString`](/v1/examples/sys/system/system.html) |

## The call

```json title="Body"
{ "connectionString": "postgresql://crm:secret@db-1:5432/crm_acme", "instanceType": "POSTGRE_SQL_DB" }
```

```json title="Answer"
{ "success": true, "statusCode": 200, "data": { "success": true, "data": true } }
```

```json title="Answer when the database refuses"
{ "success": true, "statusCode": 200, "data": { "success": false, "data": false, "error": "password authentication failed for user \"crm\"" } }
```

| Key | Meaning |
|---|---|
| `connectionString` | The string, in the format of the database : see the [connection strings](/v1/docs/Database-connection-string/mongodb-connection-strings.html) pages. |
| `instanceType` | `MONGO_DB`, `MYSQL_DB`, `MARIA_DB`, `SQL_SERVER_DB`, `POSTGRE_SQL_DB` or `ORACLE_DB`. |
| `oracleDBUsername`, `oracleDBPassword`, `oracleDBPrivilege` | Oracle : the user, the password and the privilege, as on the instance form. |

- An array of bodies checks several strings in one call and answers an array in the same order.

## From code

```typescript
const check = await g.sys.system.isValidConnectionString({ connectionString: cs, instanceType: T.EInstanceType.POSTGRE_SQL_DB });
if (!check.success) throw new Error('This database can not be reached : ' + check.error);
```

## Access and settings

- Over HTTP, a system API answers once its [settings](/v1/docs/settings/systemApiSettings.html) give it `apiAccessType: TOKEN_ACCESS` (the token of an API user whose [group](/v1/docs/apis-security/api-group-permission.html) grants this system API, in `x-am-authorization`) or `IS_PUBLIC`. Without settings it is `NO_ACCESS` : your code calls it through `g.sys`, the admin panel tests it, and an HTTP call is refused. 
- The settings can also cache the answer or require person tokens (`authProviders`) ; [pre and post hooks](/v1/docs/apis-all/hooks/preHook-api.html) run around it like around any API.
- The [request headers](/v1/docs/apis-all/header/requestHeader.html) apply : `x-am-response-case`, `x-am-content-type-response`, `x-am-internationalization`, `x-am-tenant-username`…

## Errors

| Code | When |
|---|---|
| `400` | The body is wrong : the message names the missing or invalid key. |
| `401` | No valid API user token, or the API is `NO_ACCESS` : `You are not authorized to access this API.` |
| `403` | No group grants this system API. |

## Related

- [All APIs at a glance](/v1/docs/apis-all/overview.html) · [Response format](/v1/docs/apis-all/response-format.html) · [System API settings](/v1/docs/settings/systemApiSettings.html) · [System APIs from code](/v1/examples/sys/system/system.html)