Metadata Management (MM)
REST API General Information

Table Of Content

Overview
Copyright Notice
Release Changes
- v11.1.0
- v11.0.0
API General Rules
API Key
API Response
API Server Log
Object ID Formats
Entity Formats

1. Overview

This document describes the Metadata Management (MM) SDK which is based on a REST API.

Copyright © Meta Integration Technology, Inc. 1997-2023.
All Rights Reserved.
Meta Integration® is a registered trademark of Meta Integration Technology, Inc.
Other product and company names (or logos) mentioned herein may be the trademarks of their respective owners.
http://www.metaintegration.com

3. Release Changes

v11.1.0

New Or Improved API Methods

The following API methods were added or improved with MM 11.1.0.

New or improved API methods	Group	Summary
POST /dataModel/entityRelationship	Data Model	A new API function to allow the user to create an Entity Relationship between two classifiers.
DELETE /dataModel/entityRelationship	Data Model	A new API function to allow the user to delete an Entity Relationship between two classifiers.
POST /repository/dashboard/import	Repository	A new API function to allow the user to import the dashboard JSON definition from a file.
POST /repository/dashboard/export	Repository	A new API function to allow the user to export the JSON definition of a dashboard to a file.
POST /semanticMapping/semanticLink	Semantic Mapping	A new API function to allow the user to create a new semantic link between two objects.
DELETE /semanticMapping/semanticLink	Semantic Mapping	A new API function to allow the user to delete a semantic link between two objects.
GET /entities/{objectId} GET /entities/validateMQLQuery GET /entities/countMQLQuery GET /relationships/{objectId} GET /relationships/count/{objectId}	Browse	New parameter "mqlVersion": The MQL version. The current MQL version is 3. Specify a number less than 3 if you want to use deprecated syntax and/or MQL system attributes.
POST /entities/executeMQLQuery POST /entities/getAttributeValueCounts	Browse	New property "mqlVersion" of Requst body: The MQL version. The current MQL version is 3. Specify a number less than 3 if you want to use deprecated syntax and/or MQL system attributes.
POST /entities/upgradeMQLQuery	Browse	Upgrade the Request body to the latest MQL syntax
POST /License/updateLicense	License	Update license
POST /repository/model/export	Repository	New parameter exportDataProfilingAndSampling

For more information about the MQL version, please refer to MQL Documentation.

Deprecated API Methods, Parameters or Schemas

Deprecated API methods, parameters or schemas do not require any action before upgrading to MM 11.1.0. They will continue to work as normal in MM 11.1.0. We plan to remove them in MM 12.0.

Deprecation of API methods, parameters or schemas	Replacements	More information
POST /repository/semanticMapping/exportCSV	POST /repository/model/export	Consolidate the import/export APIs
POST /repository/semanticMapping/importCSV	POST /repository/model/import	Consolidate the import/export APIs
POST /operations/glossary/exportAndDownloadCSV	POST /repository/model/export	Consolidate the import/export APIs
PUT /entities/glossary/classify	POST /semanticMapping/semanticLink	Improve mapped data documentation
PUT /entities/glossary/unclassify	DELETE /semanticMapping/semanticLink	Improve mapped data documentation
POST /repository/createRelationship	POST /dataModel/entityRelationship	New relationships as object types

Removed API Methods, Parameters or Schemas

The following table list API methods removed with MM 11.1.0 and the recommended methods to replace them. Please ensure your applications do not use any of these methods before upgrading to MM 11.1.0.

Removal of API methods, parameters or schemas

Replacements

More information

v11.0.0

New Or Improved API Methods

The following API methods were added or improved with MM 11.0.0.

New or improved API methods	Group	Summary
GET /entities/validateMQLQuery	Browse	New parameter "scope": Scope conditions in MQL syntax to further restrict the models or objects in the FROM
POST /entities/executeMQLQuery	Browse	New field "scope" in the request body: Scope conditions in MQL syntax to further restrict the models or objects in the FROM
GET /entities/countMQLQuery	Browse	New parameter "scope": Scope conditions in MQL syntax to further restrict the models or objects in the FROM
POST /entities/executeWorksheet	Browse	Get the objects of a worksheet
GET /entities/countWorksheet	Browse	Get the total number of objects of a worksheet
POST /entities/getAttributeValueCounts	Browse	New field "scope" in the request body: Scope conditions in MQL syntax to further restrict the models or objects in the FROM
POST /entities/Dataprofiling/{objectId}	Browse	New parameter ""sensitivityLabel: allow the user to propose a sensitivity label
GET /repository/dataClasses/	Data Classes	Rebrand "Semantic Type" as "Data Class"
GET /repository/dataClasses/{objectId}	Data Classes	Rebrand "Semantic Type" as "Data Class"
PUT /repository/dataClasses/{objectId}	Data Classes	Rebrand "Semantic Type" as "Data Class"
POST /dataMapping/exportScript	Data Mapping	Export a Data Mapping to data mapping script format files using the Default Server
POST /dataMapping/importScript	Data Mapping	Import the data mapping from data mapping format script files
PUT /entities/glossary/classify/{objectId}	Glossary	Classify an object with an existing term or using a new term
PUT /entities/glossary/unclassify/{objectId}	Glossary	Unclassify an object
POST /operations/glossary/exportAndDownloadCSV	Glossary	Download glossary terms that belong to a term or a list of terms recursively
GET /lineage/getOperations/{startingId}	Lineage	Get operations/transformation logic
GET /operations/listOperations	Operation	Get operations
POST /operations/downloadOperationLog/{operationId}	Operation	Download the log of an operation
POST /repository/metaModel/importXML	Repository	Import the meta model from an XML file
POST /repository/metaModel/exportXML	Repository	Export a meta model package as an XML file
POST /repository/model/import	Repository	Import the custom model or imported model from a zip file which contains the CSV files
POST /repository/model/export	Repository	Export the custom model or imported model as a zip file which contains the CSV files
POST /repository/backup	Repository	This function now backs up to a zip file
POST /repository/restore	Repository	This function now restores from a zip file
GET /admin/grants/getGlobalRoles	Roles	Get the global role(s) of a user or user group
GET /admin/grants/getGlobalGrantees	Roles	Get the users or user groups who have a particular global role
PUT /admin/grants/grantGlobalRoles	Roles	Grant a global role to a user or user group
PUT /admin/grants/revokeGlobalRole	Roles	Revoke a global role from a user or user group
GET /admin/grants/getObjectRoles/{objectId}	Roles	Get the role(s) of a user or user group on an object
GET /admin/grants/getObjectGrantees/{objectId}	Roles	Get the users or user groups who have a particular role on an object
PUT /admin/grants/grantObjectRole/{objectId}	Roles	Grant a role on an object to a user or user group
PUT /admin/grants/revokeObjectRole/{objectId}	Roles	Revoke a role on an object from a user or user group
POST /admin/grants/importGlobalRolesCSV	Roles	Import the global roles from a CSV file
POST /admin/grants/exportGlobalRolesCSV	Roles	Export the global roles as a CSV file
POST /admin/grants/importObjectRolesCSV	Roles	Import the object roles from a CSV file
POST /admin/grants/exportObjectRolesCSV	Roles	Export the object roles as a CSV file
GET /repository/sensitivityLabels/	Sensitivity Labels	Get sensitivity labels
GET /repository/sensitivityLabels/{objectId}	Sensitivity Labels	Get the sensitivity label associated with an object
PUT /repository/sensitivityLabels/{objectId}	Sensitivity Labels	Maintain the sensitivity label associated with an object
PUT /admin/users	Users	In order to update a user's password an old password is required now

Deprecated API Methods, Parameters or Schemas

Deprecated API methods, parameters or schemas do not require any action before upgrading to MM 11.0.0. They will continue to work as normal in MM 11.0.0. We plan to remove them in MM 12.0.

Deprecation of API methods, parameters or schemas	Replacements	More information
POST /repository/databaseDocumentation/exportCSV	POST /repository/model/export	Consolidate the import/export APIs
GET /repository/semanticTypes	GET /repository/dataClasses	Rebrand "Semantic Type" as "Data Class"
GET /repository/semanticTypes/{objectId}	GET /repository/dataClasses/{objectId}	Rebrand "Semantic Type" as "Data Class"
PUT /repository/semanticTypes/{objectId}	PUT /repository/dataClasses/{objectId}	Rebrand "Semantic Type" as "Data Class"
POST /entities/executeMQLQuery parameter legacyEntityFormat		This function will always return results in the MQL Entity Format
POST /entities/getAttributeDistinctValueCounts	POST /entities/getAttributeValueCounts	The new function is more efficient
POST /entities/getInferredSemanticObjects	POST /entities/executeMQLQuery	Use the system attribute "Inferred Documentation" to get inferred documentation of the object
POST /dataMapping/exportExcel	POST /dataMapping/exportScript	The output of the new function can be edited by the user and imported back via POST /dataMapping/importScript
POST /entities/DataProfiling/{objectId} parameter hideData	new parameter sensitivityLabel	Use sensitivity label to hide data
GET /types/listEntityTypes	GET /types/listObjectTypes	Rebrand entity type as object type
GET /repository/customAttributes/{nameOrId}	POST /repository/metaModel/exportXML	Rebrand custom attributes as Meta model attribute types. Export the Meta model to view the definition of any attribute type.
POST /operations/glossary/exportAndDownloadCSV	POST /repository/model/export	Specify the objectIds parameter to export a term or a list of terms.
PUT /repository/setCustomAttributes	PUT /repository/setAttributes	Rebrand custom attributes as Meta model attribute types
GET /entities/DataProfiling/{objectId}	Deprecated the following fields in the result: totalSemanticTypeRows, invalidSemanticTypeValues and inferredSemanticTypes.	Removed data classes from data profiling. Note that these fields are not set in the output.
PUT /entities/DataProfiling/{objectId}	Deprecated the following fields in the Request body: totalSemanticTypeRows, invalidSemanticTypeValues and inferredSemanticTypes.	Removed data classes from data profiling. Note that these fields in the input will be ignored.
POST /entities/glossary parameter categoryPath	new parameter termPath	Removed category from glossary
GET /types/listAttributeTypes parameter entityType	new parameter objectType	Rebrand entity type as object type
GET /types/listGroupTypes parameter entityType	new parameter objectType	Rebrand entity type as object type
Schema Entity's field entityType	new field objectType	Rebrand entity type as object type. Note that entityType and objectType are set to the same value for MM 11.0.
Schema Entity's field term	new field terms	Object can be defined by multiple terms. The field term will store the first term if the object has multiple terms.
Schema Entity's field semanticTypes	new field dataClassifications	Rebrand semantic type as data classification. Note that semanticTypes and dataClassifications are set to the same value for MM 11.0.
Enumeration type ReferenceType used by Schema GlossaryTermReference's type field	Replaced "More General" with "Specializes", "More Specific" with "Generalizes". Added "Possible Value" and "Possible Value Of".	New meta model relationships for Term
Schema ModelSettings_Create's field "Send email notification when an import"		Notifications are sent to model watchers for model changes and metadata managers for import failures. There are no more notification options in the content.
Schema ModelSettings_Create_Data's field "Data hiding"	new field "Hide data using Sensitivity Label"	Data hiding is controlled by the sensitivity label defined on the field
Schema ModelSettings_Set's field "Send email notification when an import"		Notifications are sent to model watchers for model changes and metadata managers for import failures. There are no more notification options in the content.

Removed API Methods, Parameters or Schemas

The following table list API methods removed with MM 11.0.0 and the recommended methods to replace them. Please ensure your applications do not use any of these methods before upgrading to MM 11.0.0.

Removal of API methods, parameters or schemas	Replacements	More information
GET /auth/login	POST /auth/login	Deprecated with MM 10.1.0 as the POST method is more secure
GET /auth/loginPlainText	POST /auth/loginPlainText	Deprecated with MM 10.1.0 as the POST method is more secure
GET /auth/loginOAuth2	POST /auth/loginOAuth2	Deprecated with MM 10.1.0 as the POST method is more secure
POST /entities	POST /entities/executeMQLQuery	Deprecated with MM 10.1.0 as the new function provides better functionality
POST /entities/countEntities	GET /entities/countMQLQuery	Deprecated with MM 10.1.0 as the new function provides better functionality
GET /repository/getModelImportParameters	GET /repository/importModel	Deprecated with MM 10.1.0 as the new function provides better functionality
PUT /repository/setModelImportParameters	PUT /repository/importModel	Deprecated with MM 10.1.0 as the new function provides better functionality
GET /repository/getDataParameters	GET /repository/importModel	Deprecated with MM 10.1.0 as the new function provides better functionality
PUT /repository/setDataParameters	PUT /repository/importModel	Deprecated with MM 10.1.0 as the new function provides better functionality
POST /operations/repositoryExport/attachFile	POST /repository/attachments/{objectId}	Deprecated with MM 10.1.0 as the new function provides better functionality
POST /search/entity	POST /entities/executeMQLQuery	Deprecated with MM 10.1.0 as the new function provides better functionality
POST /entities/getAttributeStatistics		Deprecated with MM 10.1.0 as this function was rarely used by users
POST /entities/getAttributeStatisticsCount		Deprecated with MM 10.1.0 as this function was rarely used by users
GET /admin/grants/{objectId}	GET /admin/grants/getObjectRoles/{objectId}	This function no longer complies with the MM 11.0 object role framework
PUT /admin/grants/{objectId}/{userGroupId}	PUT /admin/grants/grantObjectRole/{objectId} and PUT /admin/grants/revokeObjectRole/{objectId}	This function no longer complies with the MM 11.0 object role framework
GET /admin/stewards/{objectId}	GET /admin/grants/getObjectGrantees/{objectId}	This function no longer complies with the MM 11.0 object role framework
PUT /admin/stewards/{objectId}	PUT /admin/grants/grantObjectRole/{objectId} and PUT /admin/grants/revokeObjectRole/{objectId}	This function no longer complies with the MM 11.0 object role framework
POST /repository/backup parameter backupAllVersions	backupCachedModels	This parameter is deprecated with MM 10.1.0.

All steward related fields have been removed from the schemas. For example, the CreateUser and CreateUserGroup no longer have the steward field.

4. General Rules

REST API is case-sensitive. This is true for all URLs, parameter names and values, request body's keys and values, etc.

5. API Key

All API methods with a few exceptions take a header parameter "api_key" to allow user authentication. A valid value of the "api_key" can be obtained by calling the API method POST "/auth/loginPlainText" or POST "/auth/login". If you call POST "/auth/loginPlainText" the response string itself can be used as the "api_key". If you call POST "/auth/login" the "result" property of the response object can be used as the "api_key".

If you are making API calls via the MM REST API SDK Documentation (or REST API UI), you only need to login once by providing the user name and password and clicking on the Login button in the upper right corner. The MM REST API UI will inject the "api_key" header in all subsequent calls.

An "api_key" will become invalid after a "/auth/logout" call is made, the Login timeout is reached, or the Logout button in the upper right corner of the MM REST API UI is clicked.

6. API Response

All API methods with a few exceptions return a JSON "ResponseObject" in the following format:

		
		{
		  "result": "...",
		  "error": {
		    "errorCode": "...",
		    "message": "..."
		  }
		}

In general if a GET method, or sometimes a POST method, is executed successfully, the "result" property will contain the data it retrieved. If a PUT or DELETE method is executed successfully, the "result" property will usually be an empty string.

If any API method failed during execution, the "result" property will be an empty string and the "error" property will contain an error code and an error message.

Following are a few common error codes:

AUTHENTICATION_ERROR
OBJECT_NOT_FOUND
INVALID_REPOSITORY_PATH
REQUIRED_PARAMETER_NOT_SPECIFIED
INVALID_PARAMETER
OPERATION_NOT_SUPPORTED
SERVER_ERROR
LICENSE_ERROR

Some API methods may produce more than one content type. For example, POST /operations/repositoryImport/downloadModelAttachment produces content type application/x-download when an attachment file is downloaded successfully or application/json if there is an error. You need to set your request Accept header appropriately to receive the response.

If you get a Response Code 500 with such a function that may produce more than one media type, try to switch the media type from one to the other, for example, from application/x-download to application/json.

7. API Server Log

All API calls are logged in the MM system log with the following status information:

The user who made the call
The total time spent in the execution of the call
The number of (root) objects retrieved by the call

Following are a few examples of the log messages:

[http-nio-19980-exec-4] 2019-11-26 17:07:12 RESTAPI_S0001 (User '', Total: 0ms, ResultsSize: 256), REST API method: 'GET types/listProfiles'
[http-nio-19980-exec-4] 2019-11-26 17:07:12 RESTAPI_S0001 (User 'Administrator', Total: 74ms, ResultsSize: 1), REST API method: 'POST repository/createFolder'
[http-nio-19980-exec-2] 2019-11-26 17:07:12 RESTAPI_S0001 (User 'Administrator', Total: 32ms, ResultsSize: 82), REST API method: 'GET admin/groups'

8. Object ID Formats

Object ID is mostly used as a path parameter, sometimes a query parameter, and other times a property in the JSON body. The object can be a repository object, model object, glossary term, user, or group etc.

An object ID can take the following formats:

Object identifier: the concatenation of the Model Id and Object Id separated with an underscore ("_"). for example, "447_16". If the object is a repository object, the Model Id should be -1, for example, -1_4.
Object stable id: the Object stable identifier encoded in Base 64, for example, "AAEWKgAvI9AZRE0vJcG5qaLmIqLKpxodWA". Only a model object can have an object stable id. I.e. repository objects do not have stable ids.
Repository object path: the path of a repository object, for example, "/Configuration/Published". It can be used where a repository object ID is expected.

9. Entity Formats

The "result" property of many API methods represents Entity object(s) or objects that embed Entity objects. Some system attributes of an Entity object, such as Context, "Business Name Inferred Origin" and "Business Description Inferred Origin", may also contain Entity objects. For details on MM system attributes, refer to MQL Documentation.

9.1 Legacy Entity Format

A legacy Entity format consists of the following properties. Not all properties are required.

id
name
objectType
attributes
labels
parentId
term
dataClassifications

Following is a sample Entity object in the legacy Entity format:

		
		  {
		    "id": "73555_35",
		    "objectType": {
		      "name": "RDBMS Relational Database (Database).Table",
		      "displayName": "RDBMS Relational Database (Database).Table"
		    },
		    "name": "CategoryGroup",
		    "attributes": [
		      {
		        "attributeType": {
		          "name": "Last Modified Date",
		          "displayName": "Last Modified Date",
		          "type": "SYSTEM_ATTRIBUTE"
		        },
		        "value": "2018-09-24 13:47:37"
		      },
		      {
		        "attributeType": {
		          "name": "Name",
		          "displayName": "Name",
		          "type": "SYSTEM_ATTRIBUTE"
		        },
		        "value": "CategoryGroup"
		      },
		      {
		        "attributeType": {
		          "name": "Native Type",
		          "displayName": "Native Type",
		          "type": "ATTRIBUTE"
		        },
		        "value": "TABLE"
		      }
		    ],
		    "parentId": "73555_28"
		  }

9.2 MQL Entity Format

The new Entity format, also known as the MQL Entity Format, is based on the SELECT list of an MQL query. The new Entity format contains a single "attributes" property which consists of the attribute type names that appear in the "select" property. For MQL SELECT list details, refer to MQL Documentation.

Following is a sample Entity object in the MQL Entity Format which corresponds to the SELECT list: Name, "Object Type", "Object Id":

		
         {
            "attributes": [
                {
                    "attributeType": {
                        "name": "Name",
                        "displayName": "Name",
                        "type": "SYSTEM_ATTRIBUTE"
                    },
                    "value": "PurchaseOrder"
                },
                {
                    "attributeType": {
                        "name": ""\"Object Type\""",
                        "displayName": "Object Type",
                        "type": "SYSTEM_ATTRIBUTE"
                    },
                    "value": "Table"
                },
                {
                    "attributeType": {
                        "name": ""\"Object Id\""",
                        "displayName": "Object Id",
                        "type": "SYSTEM_ATTRIBUTE"
                    },
                    "value": "69585_200"
                }
            ]
        }

Every legacy Entity property can be mapped to an MM system attribute. Here is the mapping between the legacy Entity properties and MM system attributes.

Legacy Entity Property	MM System Attribute
id	"Object Id"
name	Name
objectType	"Object Type"
labels	Labels
parentId	Context
term	"Term Classification"
semanticTypes	"Data Classifications"

9.3 API Methods Returning Entity Object(s)

Some API methods return Entity objects in the Legacy Entity format only. Some API methods may return both formats depending on the value of the input. In general, the MQL Entity format is used whenever there is a "select" property/parameter specified.

API method	Legacy format	MQL format
GET /entities/{objectId}	If "select" parameter is not specified	If "select" parameter is specified
GET /relationships/{objectId}	If "select" parameter is not specified	If "select" parameter is specified
POST /entities/executeMQLQuery	If "legacyEntityFormat" is set to true	If "legacyEntityFormat" is set to false
GET /repository/getContext	Always
GET /configuration/listModels	Always
GET /entities/reports/{termId}	Always
GET /configurations/listConnectedModels	Always

The entity objects that the system attributes such as Context, "Business Name Inferred Origin" and "Business Description Inferred Origin" may have are always returned in the legacy entity format even though the object itself may be represented in the MQL entity format.

Following is a sample Entity object in the MQL Entity Format which corresponds to the SELECT list: Name, Context:

		
		{
		  "attributes": [
			{
			  "attributeType": {
				"name": "Name",
				"displayName": "Name",
				"type": "ATTRIBUTE"
			  },
			  "value": "Employee Sales by Country"
			},
			{
			  "attributeType": {
				"name": "Context",
				"displayName": "Context",
				"type": "SYSTEM_ATTRIBUTE"
			  },
			  "value": [
				{
				  "id": "20_1",
				  "objectType": {
					"name": "RDBMS Relational Database (Server).Database Server",
					"displayName": "RDBMS Relational Database (Server).Database Server"
				  },
				  "name": "Northwind"
				},
				{
				  "id": "22_1",
				  "objectType": {
					"name": "RDBMS Relational Database (Database).Database Schema",
					"displayName": "RDBMS Relational Database (Database).Database Schema"
				  },
				  "name": "dbo"
				}
			  ]
			}
		  ]
		}

The entity objects embedded within the system attributes contain only the following properties: id, name and objectType.

Metadata Management (MM)REST API General Information