Get Databases
This endpoint allows you to get information about what databases exist and the details of those. It provides many options to search on such as group_ids, database name and so on. While unlikely a connector would make use of this endpoint, it can be useful for finding databases in complex or large group structures or for a variety of more-unique applications of the API.
POST Parameters
| Parameter | Required | Value | Description |
|---|---|---|---|
api_key | {key} | An API key that has access to the resource you want to query for | |
group_id | {integer} | A Group ID where you want information for all databases that are part of this group | |
database_id | {integer} | A Database ID which you want information for such as getting its name and parent group | |
database_name | {unicode} | Get all databases which match this name which the API key has access to. While it is impossible to have the same database name within the same group, it is possible to have the same database name in other groups |
Important Requirements:
- One of group_id, database_id, or database_name must be provided (⚠️ indicates at least one is required)
- The others should be left blank when using one of these parameters
Code Examples
The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.
Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.
curl --request POST 'https://api-app.xtracta.com/v1/databases' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'api_key=<API_KEY>' \ --data-urlencode 'group_id=<GROUP_ID>'
Sample Requests
List Databases
POST https://api-app.xtracta.com/v1/databases HTTP/1.1 api_key=123&group_id=456789
Get by database_id
POST https://api-app.xtracta.com/v1/databases HTTP/1.1 api_key=123&database_id=456789
Get by database_name
POST https://api-app.xtracta.com/v1/databases HTTP/1.1 api_key=123&database_name=Suppliers
Sample Responses
List Databases
<?xml version="1.0" encoding="UTF-8"?>
<databases_response>
<status>200</status>
<message>The request has been successfully processed</message>
<database>
<id>456789</id>
<name>Suppliers</name>
<group_id>3</group_id>
</database>
<database>
<id>456790</id>
<name>Item codes</name>
<group_id>3</group_id>
</database>
</databases_response>
Get by database_id
<?xml version="1.0" encoding="UTF-8"?>
<databases_response>
<status>200</status>
<message>The request has been successfully processed</message>
<database>
<id>456789</id>
<name>Suppliers</name>
<group_id>3</group_id>
</database>
</databases_response>
Get by database_name
<?xml version="1.0" encoding="UTF-8"?>
<databases_response>
<status>200</status>
<message>The request has been successfully processed</message>
<database>
<id>456789</id>
<name>Suppliers</name>
<group_id>3</group_id>
</database>
</databases_response>
Schema Definition
Response Elements
| Element | Description |
|---|---|
<status> | A status code in response to the operation. |
<message> | Additional information about the operation – human readable. |
<database> | This element contains all of the further sub-elements with information about the database. This element can repeat if the request returns multiple databases (e.g. where the group_id or database_name are used). |
<id> | The unique ID of the database. |
<name> | The name of the database. |
<group_id> | The group ID which the database is a child of. |
Example where group_id POSTed OR database_id not POSTed
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:simpleType name="ConfidenceType">
<xs:union>
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="0"/>
<xs:maxInclusive value="100"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value=""/>
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
<xs:complexType name="DatabaseType">
<xs:sequence>
<xs:element name="id" type="xs:positiveInteger"/>
<xs:element name="name" type="xs:string"/>
<xs:element name="group_id" type="xs:positiveInteger"/>
</xs:sequence>
</xs:complexType>
<xs:element name="databases_response">
<xs:complexType>
<xs:sequence>
<xs:element name="status" type="xs:positiveInteger"/>
<xs:element name="message" type="xs:string"/>
<xs:element name="database" type="DatabaseType" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Example where database_id POSTed
Error Responses
For JSON and XML responses generated by this endpoint, the response is wrapped in databases_response and includes the HTTP status code and a message.
| Status | Message | Description |
|---|---|---|
400 | database_id must be natural number | Use a positive integer database ID. |
404 | No such database found | Check the database selector and API-key access. |
500 | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry and contact support with the request parameters and timestamp if it persists. |
Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm the API key and caller access first.