Skip to main content

Accessing Dataclass Catalog

Overview

The $catalog endpoint provides metadata about the dataclasses and attributes available in your Qodly application's datastore. This metadata facilitates the discovery of data structures and access points essential for client applications interacting with the API.

$catalog Endpoint Variants

The $catalog endpoint offers several variants to retrieve different levels of information based on your requirements:

EndpointDescription
$catalogLists all dataclasses with basic access URIs.
$catalog/$allProvides detailed information about all dataclasses and their attributes.
$catalog/{{dataClass}}Delivers detailed information about a specific dataclass.
$catalog/{{dataStoreClassFunction}}Executes a specific datastore class function if available.

Properties Returned

Common Properties

Each response from the $catalog endpoint variants includes some common properties:

KeyTypeDescription
__UNIQIDStringA unique identifier for the API response session.
__BASEIDnull/StringBase identifier, typically null, indicating no base is used.
__NAMEStringThe name of the Qodly application to identify the session context.
propertiesObjectContains additional settings or flags relevant to the response.
supportJSONEntityKeyBooleanIndicates if JSON entity keys are supported, here it is true.
methodsArray of ObjectsLists methods available for execution through the data store. For more details, please refer to the Methods Array Details section.
dataClassesArray of ObjectsLists dataclasses exposed through the API.

Methods Array

The methods array provides details about specific functionalities that can be executed through the REST API. Each method object includes the following attributes:

PropertyTypeDescription
nameStringName of the method.
applyToStringIndicates the target of the method (e.g., "dataStore").
scopeStringScope of accessibility (e.g., "public").
fromStringOrigin of the method execution capability, such as "remoteServer".
allowedOnHTTPGETBooleanSpecifies whether the method can be called via HTTP GET requests.
exposedBooleanIndicates if the method is exposed to the API.

$catalog

Purpose

Fetches a list of all dataclasses within the project, providing essential URIs for accessing more detailed metadata.

Properties Returned

Each dataclass listed by the $catalog endpoint returns the following properties:

KeyTypeDescription
nameStringThe name of the dataclass, here it is "Users".
uriStringURI to obtain detailed metadata about the dataclass.
dataURIStringURI to access the actual data directly from the dataclass.
tip

Only the exposed dataclasses are shown in this list for your project's datastore. For more information, please refer to Configuring Data Access section.

Sample Usage Example in Postman

How to Use:

  • Method: GET
  • URL: {{APIEndpoint}}/rest/$catalog

The response structure for the $catalog endpoint looks something like this in practice:

{
"__UNIQID": "F182BFDB899C45A587EFA25AE271891D",
"__BASEID": null,
"__NAME": "plum-rap",
"properties": {
"supportJSONEntityKey": true
},
"methods": [
{
"name": "checkAvailability",
"applyTo": "dataStore",
"scope": "public",
"from": "remoteServer",
"allowedOnHTTPGET": false,
"exposed": true
}
],
"dataClasses": [
{
"name": "Users",
"uri": "/rest/$catalog/Users",
"dataURI": "/rest/Users"
}
]
}

$catalog/$all

Purpose

Provides exhaustive details on each dataclass and their attributes, enhancing understanding of data structure and types.

Properties Returned

This endpoint enriches the response with detailed attributes of each dataclass:

KeyTypeDescription
dataClassesArrayLists all data classes exposed through the API, detailing each class and its associated data and metadata.
info

For a detailed breakdown of individual dataclasses and their specific attributes, please refer to the detailed documentation in the $catalog/{{dataClass}} section.

Sample Usage Example in Postman

How to Use:

  • Method: GET
  • URL: {{APIEndpoint}}/rest/$catalog/$all

The response structure for the $catalog/$all endpoint looks something like this in practice:

{
"__UNIQID": "F182BFDB899C45A587EFA25AE271891D",
"__BASEID": null,
"__NAME": "plum-rap",
"properties": {
"supportJSONEntityKey": true
},
"methods": [
{
"name": "checkAvailability",
"applyTo": "dataStore",
"scope": "public",
"from": "remoteServer",
"allowedOnHTTPGET": false,
"exposed": true
}
],
"dataClasses": [
{
"name": "Users",
"className": "Users",
"collectionName": "UsersSelection",
"exposed": true,
"tableNumber": 4,
"scope": "public",
"uuid": "FA61573F7FB84A8D83CD04215B757F34",
"dataURI": "/rest/Users",
"extraProperties": {
"panelColor": "rgb(68,68,68)",
"position": {
"x": -169.20168158481,
"y": 246.41374517022
}
},
"attributes": [
{
"name": "ID",
"kind": "storage",
"fieldPos": 1,
"scope": "public",
"exposed": true,
"uuid": "94A7339AE34D4C4C8B0F870D975717EC",
"indexed": true,
"unique": true,
"not_null": true,
"autosequence": true,
"type": "long",
"identifying": true
},
{
"name": "Name",
"kind": "storage",
"fieldPos": 2,
"scope": "public",
"exposed": true,
"uuid": "40ED3EBC298147FBA23CA0C03107A2C6",
"type": "string"
}
],
"key": [
{
"name": "ID"
}
]
}
]
}

$catalog/{{dataClass}}

Purpose

Fetches comprehensive information about a specific dataclass, including its attributes and their properties.

Properties Returned (dataClasses Array)

The properties of the dataclasses returned by the API are:

KeyTypeDescription
nameStringThe name of the dataclass.
classNameStringThe class name as defined in the datastore.
collectionNameStringThe name used for entity collections derived from this dataclass.
exposedBooleanIndicates if the dataclass is exposed to the API.
tableNumberIntegerNumerical identifier for the table in the database.
scopeStringVisibility scope of the dataclass (e.g., 'public').
uuidStringA unique identifier for the dataclass.
dataURIStringAPI endpoint URI for accessing the dataclass's data.
extraPropertiesObjectContains additional, non-standard properties of the dataclass.
panelColorStringColor configuration for UI elements, if applicable.
positionObjectPosition settings for UI elements, defined by coordinates x and y.
attributesArray of ObjectsDefines the attributes (fields) available within the dataclass.
info

Each dataclass includes various attributes, the details of which are described in the subsequent section on attributes properties.

attributes Array Details

Each attribute within a dataclass has properties that describe its configuration and purpose within the datastore:

KeyTypeDescription
nameStringThe name of the attribute.
kindStringThe type of attribute (e.g., 'storage', 'relatedEntities').
fieldPosIntegerPosition of the attribute in the database table.
scopeStringVisibility scope of the attribute (e.g., 'public').
exposedBooleanIndicates if the attribute is exposed to the API.
uuidStringA unique identifier for the attribute.
indexedBooleanIndicates if the attribute is indexed.
uniqueBooleanIndicates if the attribute must be unique.
not_nullBooleanIndicates if the attribute must not be null.
autosequenceBooleanIndicates if the attribute uses auto-incrementing.
typeStringData type of the attribute (e.g., 'long', 'string').
identifyingBooleanIndicates if the attribute is a primary key.
reversePathBooleanFor related entities, indicates if the relationship is inverse.
pathStringPath to the related dataclass for relationship definitions.
keyArrayDefines the primary key attributes for the dataclass.

Sample Usage Example in Postman

How to Use:

  • Method: GET
  • URL: {{APIEndpoint}}/rest/$catalog/{{dataClass}}, e.g., {{APIEndpoint}}/rest/$catalog/Users

The response structure for the $catalog/{{dataClass}} endpoint looks something like this in practice:

{
"__UNIQID": "F182BFDB899C45A587EFA25AE271891D",
"__BASEID": null,
"__NAME": "plum-rap",
"properties": {
"supportJSONEntityKey": true
},
"methods": [
{
"name": "checkAvailability",
"applyTo": "dataStore",
"scope": "public",
"from": "remoteServer",
"allowedOnHTTPGET": false,
"exposed": true
}
],
"dataClasses": [
{
"name": "Users",
"className": "Users",
"collectionName": "UsersSelection",
"exposed": true,
"tableNumber": 4,
"scope": "public",
"uuid": "FA61573F7FB84A8D83CD04215B757F34",
"dataURI": "/rest/Users",
"extraProperties": {
"panelColor": "rgb(68,68,68)",
"position": {
"x": -169.20168158481,
"y": 246.41374517022
}
},
"attributes": [
{
"name": "ID",
"kind": "storage",
"fieldPos": 1,
"scope": "public",
"exposed": true,
"uuid": "94A7339AE34D4C4C8B0F870D975717EC",
"indexed": true,
"unique": true,
"not_null": true,
"autosequence": true,
"type": "long",
"identifying": true
},
{
"name": "Name",
"kind": "storage",
"fieldPos": 2,
"scope": "public",
"exposed": true,
"uuid": "40ED3EBC298147FBA23CA0C03107A2C6",
"type": "string"
}
],
"key": [
{
"name": "ID"
}
]
}
]
}