Metadata Management (MM)
REST API General Information

Table Of Content

  1. Overview
  2. Copyright Notice
  3. Release Changes
    1. New Or Improved API Methods
    2. Deprecated API Methods
    3. Removed API Methods, Parameters or Schemas
  4. API General Rules
  5. API Key
  6. API Response
  7. API Server Log
  8. Object ID Formats
  9. Entity Formats
    1. Legacy Entity Format
    2. MQL Entity Format
    3. API Methods Returning Entity Object(s)

1. Overview

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

2. Copyright Notice

Copyright © Meta Integration Technology, Inc. 1997-2021.
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

3.1 New Or Improved API Methods

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

New or improved API methods

Group

Summary

GET /admin/grants/getGlobalRoles

Users

Get the global role(s) of a user or user group

GET /admin/grants/getGlobalGrantees

Users

Get the users or user groups who have a particular global role

PUT /admin/grants/grantGlobalRoles

Users

Grant a global role to a user or user group

PUT /admin/grants/revokeGlobalRole

Users

Revoke a global role from a user or user group

GET /admin/grants/getObjectRoles/{objectId}

Users

Get the role(s) of a user or user group on an object

GET /admin/grants/getObjectGrantees/{objectId}

Users

Get the users or user groups who have a particular role on an object

PUT /admin/grants/grantObjectRole/{objectId}

Users

Grant a role on an object to a user or user group

PUT /admin/grants/revokeObjectRole/{objectId}

Users

Revoke a role on an object from a user or user group

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/getAttributeValueCounts

Browse

New field "scope" in the request body: Scope conditions in MQL syntax to further restrict the models or objects in the FROM

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}

dataClasses

Rebrand "Semantic Type" as "Data Class"

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

GET /operations/listOperations

Operation

Get operations

POST /operations/downloadOperationLog/{operationId}

Operation

Download the log of an operation

3.2 Deprecated API Methods, Parameters or Schemas

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

Deprecation of API methods, parameters or schemas

Replacements

More information

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/getAttributeDistinctValueCounts

POST /entities/getAttributeValueCounts

The new function is more efficient

GET /types/listEntityTypes

GET /types/listObjectTypes

Rebrand entity type as object type

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 semanticTypes

new field dataClasses

Rebrand semantic type as data class. Note that semanticTypes and dataClasses are set to the same value for MM 11.0.

3.3 Removed API Methods, Parameters or Schemas

The following table list API methods removed with MM 11.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.

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:

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:

Following are a few examples of the log messages:

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:

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.

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

entityType

"Object Type"

labels

Labels

parentId

Context

term

Term

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 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.