Public API v2 → List Schemas

About the /schema/list endpoint

The /schema/list endpoint lists physical schemas, business schemas, or all schemas that a user owns or has access rights to.

Only users who have permission to access physical schemas or business schemas can use the /schema/list endpoint to list the schemas they have access rights to.

For information about how to get started with Public API v2, refer to References → Public API v2.

Note

You must use the HTTPS scheme to be able to successfully run the API endpoints. Additionally, you must specify the tenant name (case-sensitive) in the endpoint request URL starting with the 2023.7.0 release.

Request URL

https://<cluster_URL>/incorta/api/v2/{tenantName}/schema/list?schemaType=<schematype>

Request URL Parameters

Parameter	Type	Description	Required
tenantName	String	The tenant name (case-sensitive)	Required starting with 2023.7.0
schemaType	String	Specify the type of the schemas you want to list. Valid values are: ● ALL ● BUSINESS (default) ● PHYSICAL If not defined, only business schemas are listed.	Optional

HTTP method

POST

Request headers

{
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access_token}"
}

You must use a valid access token of a tenant user. For information about how to create an access token, refer to Public API v2 → Create an API access token.

Request body

{
  "limit": number,
  "offset": number,
  "sortBy": "string"
}

Request body parameters

The following table describes the request body parameters in the /schema/list endpoint.

Parameter	Type	Description	Required?	Values
limit	Integer	The maximum number of schemas to return, accounting for the offset you define. This simulates the pagination of lists in the application.	Required	Between 0 and 200. A value of 0 means all schemas if their number is less than or equal to 200, otherwise, the endpoint returns only 200 schemas.
offset	Integer	The number of schemas to skip before returning the schemas defined in the `limit` parameter	Required	Between 0 and 2147483647 (the maximum value of an integer)
sortBy	String	The sorting field and order of the schema list. This applies to the original list and the returned list. Case-sensitive	Optional	Valid values are: ● NAME_ASC ● NAME_DESC ● OWNER_ASC ● OWNER_DESC ● MODIFICATION_DATE_ASC ● MODIFICATION_DATE_DESC

Request body example

{
  "limit": 2,
  "offset": 1,
  "sortBy": "NAME_DESC"
}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
200	OK The endpoint successfully ran and returned the schemas that the user owns or has access rights to	`{"limit": 0, "offset": 0, "total": 0, "schemasDetails": []}`
400	Bad Request You provided invalid values.	`{"message": "string"}` Example: `{"Cannot deserialize value of type com.incorta.publicapi.model.schema.common.SchemaProperties$SchemasListSortBy from String "Name_Desc": not one of the values accepted for Enum class: [MODIFICATION_DATE_ASC, NAME_DESC, OWNER_DESC, MODIFICATION_DATE_DESC, OWNER_ASC, NAME_ASC]... "}`
401	Unauthorized The endpoint couldn’t return the schema list due to authentication errors, such as an invalid or expired access token, or the tenant name doesn’t match the tenant in the access token.	`{"message": "string"}` Example: `{"message": "INC_09030108: Invalid authentication header. Invalid Token [abcd1234]"`
404	Not Found The tenant doesn't exist or is disabled.	`{"message": "string"}`
422	Unprocessable Entity You provided a value for the `limit` or `offset` that is out of the accepted range.	`{"errorMessages":[{"message": "string"}]}` Example: `{"errorMessages": [{"message": "INC_01210000: offset must be between 0 and 2147483647"}, {"message": "INC_01210000: limit must be between 0 and 200"}]}`
500	Internal Server Error The endpoint couldn’t return the schema list due to a server error.	`{"message": "string"}`

Response parameters

The following are the parameters in the /schema/list endpoint response when the endpoint returns the schema list and details successfully (code 200).

{
  "limit": integer,
  "offset": integer,
  "total": integer,
  "schemasDetails": [
    {
      "schemaID": integer,
      "schemaName": "string",
      "schemaDescription": "string",
      "schemaType": "string",
      "owner": "string",
      "lastModified": string(date-time),
      "isEmpty": boolean
    },
    ...
   ]}

The following table describes these response parameters.

Parameter	Description
limit	The maximum number of schemas to return, which you defined in the request.
offset	The number of skipped schemas, which you defined in the request.
total	The total number of schemas (of the selected types) that the owner of the access token owns or has access rights to.
schemasDetails	The details of each schema that the endpoint returns
SchemasDetails > schemaID	The schema ID as defined in the system metadata database
SchemasDetails > schemaName	The schema name
SchemasDetails > schemaDescription	The schema description
SchemasDetails > schemaType	The schema type: ● BUSINESS ● PHYSICAL
SchemasDetails > owner	The name of the schema owner
SchemasDetails > lastModified	The timestamp of the last modified date and time
SchemasDetails > isEmpty	Specifies if the schema is empty or not

Response example

{
  "limit": 0,
  "offset": 0,
  "total": 9,
  "schemasDetails": [
    {
    "schemaID": 391,
    "schemaName": "HR_Bsch",
    "schemaDescription": "",
    "schemaType": "BUSINESS",
    "owner": "Schema Manager",
    "lastModified": 1679576492000,
    "isEmpty": false
    },
    ...
   ]}

Content