Data Governance
Also available as:
PDF
loading table of contents...

Atlas Business Taxonomy

The Atlas Business Taxonomy is a hierarchical collection of "Terms" objects. Each Term has two important attributes: name and description. Terms can be defined under a predefined Taxonomy object, or under another Term. The predefined Taxonomy object is referred to as a “Catalog”.

Once created, a Term can be associated with any entity in Atlas. This is similar to how Classification instances can be associated with any entity. Unlike Classifications, Terms can be deleted.

Create a Term

Description:

To create a Term, you must provide a Term name. You can also provide an optional description.

Request:

POST http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/{term_name}

Request Body:

The body for this request contains a single element: {"description":string}.

Response:

The response contains the following map:

{"href":<url_for_created_term_resource>,"Status":"201"}

The "href" attribute contains the resource URL for the new Term.

Example Request:

POST http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/term1

Example Request Body:

{"description":"This is term1"}

Example Response:

{
"href":"http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1",
"Status":"201"
}

Create a Term Under Another Term

Description:

To create a Term under another Term, you must first determine the URL of the created Term. This is a recursive URL that takes the following form:

http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/{term_name}/terms/.../terms/{term_name}

Then the request takes the form:

POST {resource_url_of_parent_term}/terms/{term_name}

Example Request:

POST http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/term1

Example Request Body:

{"description":"This is term1"}

Example Response:

{
"href":"http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1",
"Status":"201"
}

Retrieve a Term Definition

Description:

Retrieve the definition for a specific Term.

Request:

GET http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/{term_name}/terms/.../terms/{term_name}

Response:

The response has the following structure:

[
  {
    "href": url_of_term,
    "name": fully_qualified_name_of_term,
    "description": description_of_term,
    "available_as_tag": true,
    "creation_time": timestamp,
    "hierarchy": {
      ...
    },
    "terms": {
      "href": url_of_terms_under_this_term
    }
  }
]

Response field descriptions:

  • href – The resource URL for the Term.

  • name – The fully qualified name of this Term. By fully qualified, we mean the entire path starting from the Business Taxonomy name, along with all intermediate parent terms above the Term. These components are separated by a "." character.

  • description – The description provided when the Term was created.

  • System-defined properties such as creation_time are also included.

  • terms – Contains a single href element with the URL to use to retrieve the Terms under this Term.

Example Request:

GET http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11

Example Response:

[
  {
    "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11",
    "name": "Catalog.term1.term11",
    "description": "This is term11",
    "available_as_tag": true,
    "creation_time": "2016-06-20:03:14:42",
    "hierarchy": {
      "path": "/term1",
      "short_name": "term11",
      "taxonomy": "d"
    },
    "terms": {
      "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11/terms"
    }
  }
]

List All Terms

Description:

List all Terms in the Catalog Taxonomy hierarchy.

Request:

GET http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms

Response:

The response is an array of results:

[
  {
    "href": url_of_term,
    "name": fully_qualified_name_of_term,
    "description": description_of_term
  },
  ...
]

Each element in the array is a descendant of the Catalog hierarchy of business Terms.

Response field descriptions:

  • href – The resource URL for the Term.

  • name – The fully qualified name of this Term. By fully qualified, we mean the entire path starting from the Business Taxonomy name, along with all intermediate parent terms above the Term. These components are separated by a "." character.

  • description – The description provided when the Term was created.

Example Request:

GET http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms

Example Response:

[
  {
    "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1",
    "name": "Catalog.term1",
    "description": "This is Term1"
  },
  {
    "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11",
    "name": "Catalog.term1.term11",
    "description": "This is term11"
  },
  {
    "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11/terms/term111",
    "name": "Catalog.term1.term11.term111"
  },
  {
    "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term12",
    "name": "Catalog.term1.term12"
  }
]

List All Terms Under a Term

Description:

List all Terms under a specified Term.

Request:

GET http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/{term_name}/terms/.../terms/{term_name}/terms

Response:

The response is an array of results:

[
  {
    "href": url_of_term,
    "name": fully_qualified_name_of_term,
    "description": description_of_term
  },
  ...
]

Each element in the array is a descendant of the Term specified in the request.

Response field descriptions:

  • href – The resource URL for the Term.

  • name – The fully qualified name of this Term. By fully qualified, we mean the entire path starting from the Business Taxonomy name, along with all intermediate parent terms above the Term. These components are separated by a "." character.

  • description – The description provided when the Term was created.

Example Request:

GET http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11/terms

Example Response:

[
  {
    "href": "http://localhost:21000/api/atlas/v1/taxonomies/Catalog/terms/term1/terms/term11/terms/term111",
    "name": "Catalog.term1.term11.term111"
  },
]

Associate a Term with an Entity

Description:

To associate a Term with an entity, you must provide the entity GUID and the fully qualified name of the Term.

Request:

POST http://<atlas-server-host:port>/api/atlas/v1/entities/{entity_guid}/tags/{fully_qualified_name_of_term}

The request body is an empty map.

Response:

{"href":url_for_created_resource,"status":"201"}

Example Request:

POST http://<atlas-server-host:port>/api/atlas/v1/entities/f4019a65-8948-46f1-afcf-545baa2df99f/tags/Catalog.term1.term12

Disassociate a Term from an Entity

Description:

To disassociate a Term with an entity, you must provide the entity GUID and the fully qualified name of the Term.

Request:

DELETE http://<atlas-server-host:port>/api/atlas/v1/entities/{entity_guid}/tags/{fully_qualified_name_of_term}

Response:

{"href":url_for_deleted_resource,"status":"200"}

Example Request:

DELETE http://<atlas-server-host:port>/api/atlas/v1/entities/f4019a65-8948-46f1-afcf-545baa2df99f/tags/Catalog.term1.term12

Delete a Term

Description:

Deleting a Term removes it from the Business Catalog Taxonomy and also removes all entity associations with the Term. In addition, all child Terms under the deleted Term in the Catalog hierarchy are also deleted. Note that depending on the depth of the hierarchy and the number of associations for the term and its sub-terms, this could be an expensive operation in terms of system resources.

Request:

DELETE http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/{term_name}/terms/.../terms/{term_name}

Response:

{"href":url_for_deleted_resource,"status":"200"}

Example Request:

DELETE http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/term1

Update a Term

Description:

Currently, the only Term attribute that can be updated is the description. Updating a Term description also updates this property in all associated entities.

Request:

PUT http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/{term_name}/terms/.../terms/{term_name}

Request Body:

{"description":"updated_description"}

Response:

{"href":url_for_updated_resource,"status":"200"}

Example Request:

PUT http://<atlas-server-host:port>/api/atlas/v1/taxonomies/Catalog/terms/term2