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

Atlas Entity API

Summary:

These API endpoints can be used to create, read, update, and delete a single entity.

  • Base resource name: v2/entity

  • Full URL: http://<atlas-server-host:port>/api/atlas/v2/entity

Create or Update a Single Entity

Request:

POST v2/entity

Description:

Create or update a single entity.

Method Signature:

@POST
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
public EntityMutationResponse createOrUpdate(final AtlasEntity entity) throws AtlasBaseException { 

Example Request:

This example request creates a spark_dataframe entity type.

PUT /v2/entity/

Example Request Body:

{
  "typeName": "spark_dataframe",
  "attributes" : {

     "qualifiedName" : "spark_dataframe_qualifiedName",
     "name" : "spark_dataframe_entity",
    "source" : "hdfs://vimal-fenton-4-1.openstacklocal:8020/apps/hive/warehouse/source",
    "destination" : "hdfs://vimal-fenton-4-1.openstacklocal:8020/apps/hive/warehouse/destination"
  },
  "classifications": [

  ]
 
}

Example Response:

{
  "entitiesMutated": {
    "CREATE_OR_UPDATE": [
      {
        "guid": "b42350c8-665b-4ff9-bdb5-16cf432412f7"
      }
    ]
  }
}

Update Entity Using GUID

Request:

PUT /v2/entity/guid/{guid}

Description:

This request is used to update an Entity by referencing its GUID.

Method Signature:

@PUT
@Path("guid/{guid}")
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
public EntityMutationResponse updateByGuid(@PathParam("guid") String guid, AtlasEntity entity, @DefaultValue("false") @QueryParam("partialUpdate") boolean partialUpdate) throws AtlasBaseException { 

Example Request:

PUT /v2/entity/guid/b42350c8-665b-4ff9-bdb5-16cf432412f7

Example Request Body:

{
  "typeName": "spark_dataframe",
  "attributes" : {

     "qualifiedName" : "spark_dataframe_qualifiedName",
     "name" : "spark_dataframe_entity",
    "source" : "/new/source/path",
    "destination" : "/new/destination/path"
  },
  "classifications": [

  ]
 
}

Example Response:

{
  "entitiesMutated": {
    "CREATE_OR_UPDATE": [
      {
        "guid": "b42350c8-665b-4ff9-bdb5-16cf432412f7"
      }
    ]
  }
}

Get Entity Definition Using GUID

Request:

GET v2/entity/guid/{guid}

Description:

Returns an Entity definition by referencing its GUID.

Method Signature:

@GET
@Path("/guid/{guid}")
@Produces(Servlets.JSON_MEDIA_TYPE)
public AtlasEntity getById(@PathParam("guid") String guid) throws AtlasBaseException { 

Example Request:

GET v2/entity/guid/b42350c8-665b-4ff9-bdb5-16cf432412f7

Example Response:

{
  "typeName": "spark_dataframe",
  "attributes": {
    "source": "/new/source/path",
    "description": null,
    "qualifiedName": "spark_dataframe_qualifiedName",
    "name": "spark_dataframe_entity",
    "owner": null,
    "destination": "/new/destination/path"
  },
  "guid": "b42350c8-665b-4ff9-bdb5-16cf432412f7"
}

Get Entity Definition and Associations Using GUID

Request:

GET v2/entity/guid/{guid}/associations

Description:

Returns an Entity definition and all of its associations, such as classifications and terms, by referencing its GUID.

Method Signature:

@GET
@Path("/guid/{guid}/associations")
@Produces(Servlets.JSON_MEDIA_TYPE)
public AtlasEntityWithAssociations getWithAssociationsByGuid(@PathParam("guid") String guid) throws AtlasBaseException { 

Example Request:

GET v2/entity/guid/b42350c8-665b-4ff9-bdb5-16cf432412f7/associations

Example Response:

{
  "typeName": "spark_dataframe",
  "attributes": {
    "source": "/new/source/path",
    "description": null,
    "qualifiedName": "spark_dataframe_qualifiedName",
    "name": "spark_dataframe_entity",
    "owner": null,
    "destination": "/new/destination/path"
  },
  "guid": "b42350c8-665b-4ff9-bdb5-16cf432412f7"
}

Delete Entity Using GUID

Request:

DELETE /v2/entity/guid/{guid}

Description:

Deletes an Entity by referencing its GUID.

Method Signature:

@DELETE
@Path("guid/{guid}")
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
public EntityMutationResponse deleteByGuid(@PathParam("guid") final String guid) throws AtlasBaseException { 

Example Request:

DELETE v2/entity/guid/b42350c8-665b-4ff9-bdb5-16cf432412f7

Example Response:

{
  "entitiesMutated": {
    "DELETE": [
      {
        "guid": "b42350c8-665b-4ff9-bdb5-16cf432412f7"
      }
    ]
  }
}

Update a Subset of Entity Attributes

Request:

PUT /v2/entity/uniqueAttribute/type/{typeName}/attribute/{attrName}

Description:

Updates a subset of attributes based on Entity type and a unique attribute, such as Referenceable.qualifiedName. Null updates are not allowed.

Method Signature:

@Deprecated
@PUT
@Consumes(Servlets.JSON_MEDIA_TYPE)
@Produces(Servlets.JSON_MEDIA_TYPE)
@Path("/uniqueAttribute/type/{typeName}/attribute/{attrName}")
public EntityMutationResponse partialUpdateByUniqueAttribute(@PathParam("typeName") String entityType,
    @PathParam("attrName") String attribute,
    @QueryParam("value") String value, AtlasEntity entity) throws Exception { 

Example Request:

PUT v2/entity/uniqueAttribute/type/spark_dataframe/attribute/qualifiedName?value=spark_dataframe_qualifiedName

Example Request Body:

{
  "typeName": "spark_dataframe",
  "attributes" : {

    "qualifiedName" : "spark_dataframe_qualifiedName",
    "name" : "spark_dataframe_entity",
    "source" : "/new/source/path",
    "destination" : "/new/destination/path"
  },
  "classifications": [

  ]
 
}

Example Response:

{
  "entitiesMutated": {
    "CREATE_OR_UPDATE": [
      {
        "guid": "3942dc63-cdae-4f67-b7a3-e33723ffae3e"
      }
    ]
  }
}

Delete Entity Using Type and Unique Attribute

Request:

DELETE /v2/entity/uniqueAttribute/type/{typeName}/attribute/{attrName}

Description:

Deletes an Entity referenced by an Entity type and a unique attribute, such as Referenceable.qualifiedName.

Method Signature:

@Deprecated
@DELETE
@Consumes(Servlets.JSON_MEDIA_TYPE)
@Produces(Servlets.JSON_MEDIA_TYPE)
@Path("/uniqueAttribute/type/{typeName}/attribute/{attrName}")
public EntityMutationResponse deleteByUniqueAttribute(@PathParam("typeName") String entityType,
    @PathParam("attrName") String attribute,
    @QueryParam("value") String value) throws Exception { 

Example Request:

DELETE v2/entity/uniqueAttribute/type/spark_dataframe/attribute/qualifiedName?value=spark_dataframe_qualifiedName

Example Response:

{
  "entitiesMutated": {
    "DELETE": [
      {
        "guid": "3942dc63-cdae-4f67-b7a3-e33723ffae3e"
      }
    ]
  }
}

Get Entity Definition Using Type and Unique Attribute

Request:

GET /v2/entity/uniqueAttribute/type/{typeName}/attribute/{attrName}

Description:

Returns an Entity definition by referencing its Entity type and a unique attribute, such as Referenceable.qualifiedName.

Method Signature:

@Deprecated
@GET
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
@Path("/uniqueAttribute/type/{typeName}/attribute/{attrName}")
public AtlasEntity getByUniqueAttribute(@PathParam("typeName") String entityType,
    @PathParam("attrName") String attribute,
    @QueryParam("value") String value) throws AtlasBaseException { 

Example Request:

GET v2/entity/uniqueAttribute/type/spark_dataframe/attribute/qualifiedName?value=spark_dataframe_qualifiedName

Example Response:

{
  "typeName": "spark_dataframe",
  "attributes": {
    "source": "hdfs://vimal-fenton-4-1.openstacklocal:8020/apps/hive/warehouse/source",
    "description": null,
    "qualifiedName": "spark_dataframe_qualifiedName",
    "name": "spark_dataframe_entity",
    "owner": null,
    "destination": "hdfs://vimal-fenton-4-1.openstacklocal:8020/apps/hive/warehouse/destination"
  },
  "guid": "6fe47044-04f8-4bb1-9abf-765d7a5ada2a"
}

Add Classifications to an Entity Referenced by GUID

Request:

POST v2/entity/guid/{guid}/classifications

Description:

Adds classifications to an Entity referenced by its GUID.

Method Signature:

@POST
@Path("/guid/{guid}/classifications")
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
public void addClassifications(@PathParam("guid") final String guid, List<AtlasClassification> classifications) throws AtlasBaseException { 

Example Request:

POST v2/entity/guid/6fe47044-04f8-4bb1-9abf-765d7a5ada2a/classifications

Example Request Body:

[
    {
    	"typeName" : "PII"
    }
]

Update Entity Classifications Referenced by GUID

Request:

PUT v2/entity/guid/{guid}/classifications

Description:

Updates one or more classifications of an Entity referenced by its GUID.

Method Signature:

@PUT
@Path("/guid/{guid}/classifications")
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
public void updateClassifications(@PathParam("guid") final String guid, List<AtlasClassification> classifications) throws AtlasBaseException { 

Example Request:

PUT v2/entity/guid/6fe47044-04f8-4bb1-9abf-765d7a5ada2a/classifications

Example Request Body:

[
    {
    	"typeName" : "PII"
    },
    {
    	"typeName" : "Secure"
    }
]

Get Entity Classifications Using GUID

Request:

GET v2/entity/guid/{guid}/classifications

Description:

Returns the classifications of an Entity referenced by its GUID.

Method Signature:

@GET
@Path("/guid/{guid}/classifications")
@Produces(Servlets.JSON_MEDIA_TYPE)
public AtlasClassification.AtlasClassifications getClassifications(@PathParam("guid") String guid) throws AtlasBaseException { 

Example Request:

GET v2/entity/guid/6fe47044-04f8-4bb1-9abf-765d7a5ada2a/classifications

Example Response:

GET v2/entity/guid/6fe47044-04f8-4bb1-9abf-765d7a5ada2a/classifications

Response
{
  "list": [
    {
      "typeName": "PII"
    },
    {
      "typeName": "Secure"
    }
  ],
  "startIndex": 0,
  "pageSize": 0,
  "totalCount": 0
}

Delete Entity Classification Using GUID

Request:

DELETE v2/entity/guid/{guid}/classification/PII

Description:

Deletes a given classification of an Entity referenced by its GUID.

Method Signature:

@DELETE
@Path("/guid/{guid}/classification/{classificationName}")
@Consumes({Servlets.JSON_MEDIA_TYPE, MediaType.APPLICATION_JSON})
@Produces(Servlets.JSON_MEDIA_TYPE)
public void deleteClassification(@PathParam("guid") String guid,
    @PathParam("classificationName") String classificationName) throws AtlasBaseException { 

Example Request:

DELETE v2/entity/guid/6fe47044-04f8-4bb1-9abf-765d7a5ada2a/classification/PII

Example Response:

After running the DELETE, the following GET:

GET v2/entity/guid/6fe47044-04f8-4bb1-9abf-765d7a5ada2a/classifications 

Returns the following response:

{
  "list": [
    {
      "typeName": "Secure"
    }
  ],
  "startIndex": 0,
  "pageSize": 0,
  "totalCount": 0
}