Example AtlasEntity REST API POST query

[#1]

Please could someone provide me with an example AtlasEntity REST API POST query I can use on my sandbox please. I'm struggling to post a successful one with v0.8.

I managed to create a type OK. Here's my entity type.

POST http://127.0.0.1:21000/api/atlas/v2/types/typedefs

{
   "enumDefs":[],
   "structDefs":[],
   "classificationDefs":[],
   "entityDefs":[
      {
         "superTypes":[
           "DataSet"
         ],
         "name":"test_entity_7",
         "description":"test_entity_7",
         "createdBy": "admin",
         "updatedBy": "admin",
         "attributeDefs":[
            {
               "name":"test_7_1",
               "isOptional":true,
               "isUnique":false,
               "isIndexable":false,
               "typeName":"string",
               "valuesMaxCount":1,
               "cardinality":"SINGLE",
               "valuesMinCount":0
            },
           {
               "name":"test_7_2",
               "isOptional":true,
               "isUnique":false,
               "isIndexable":false,
               "typeName":"string",
               "valuesMaxCount":1,
               "cardinality":"SINGLE",
               "valuesMinCount":0
            }
         ]
         
      }
   ]
}

I know the entity is supposed to be in this form, but could someone help me relate this back to my example type please? (I'm not a coder so I have to learn though examples.)

POST http://127.0.0.1:21000/api/atlas/v2/entity

{
  "entity" : {
    "guid" : "...",
    "status" : "ACTIVE",
    "createdBy" : "...",
    "updatedBy" : "...",
    "createTime" : 12345,
    "updateTime" : 12345,
    "version" : 12345,
    "classifications" : [ {
      "typeName" : "...",
      "attributes" : {
        "property1" : { },
        "property2" : { }
      }
    }, {
      "typeName" : "...",
      "attributes" : {
        "property1" : { },
        "property2" : { }
      }
    } ],
    "typeName" : "...",
    "attributes" : {
      "property1" : { },
      "property2" : { }
    }
  },
  "referredEntities" : {
    "property1" : {
      "guid" : "...",
      "status" : "ACTIVE",
      "createdBy" : "...",
      "updatedBy" : "...",
      "createTime" : 12345,
      "updateTime" : 12345,
      "version" : 12345,
      "classifications" : [ {
        "typeName" : "...",
        "attributes" : {
          "property1" : { },
          "property2" : { }
        }
      }, {
        "typeName" : "...",
        "attributes" : {
          "property1" : { },
          "property2" : { }
        }
      } ],
      "typeName" : "...",
      "attributes" : {
        "property1" : { },
        "property2" : { }
      }
    },
    "property2" : {
      "guid" : "...",
      "status" : "DELETED",
      "createdBy" : "...",
      "updatedBy" : "...",
      "createTime" : 12345,
      "updateTime" : 12345,
      "version" : 12345,
      "classifications" : [ {
        "typeName" : "...",
        "attributes" : {
          "property1" : { },
          "property2" : { }
        }
      }, {
        "typeName" : "...",
        "attributes" : {
          "property1" : { },
          "property2" : { }
        }
      } ],
      "typeName" : "...",
      "attributes" : {
        "property1" : { },
        "property2" : { }
      }
    }
  }
}
                
              

[#2 · Accepted solution]

Please try this:

{
  "entity": {
    "typeName": "test_entity_7",
    "attributes": {
      "description": "test decription",
      "name": "entity_name",
      "owner": "admin",
      "qualifiedName": "entity_name@cluster1",
      "test_7_1": "attr1",
      "test_7_2": "attr2"
    },
    "guid": -1
  },
  "referredEntities": {}
}

The attribute list is little tricky when it comes to reading the class structure and then inferring the JSON serialization.

I copied the contents of the json above to atlasTypeCreation.json file and then used the CURL command below:

curl -g -X POST -u admin:admin -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d @/Users/amestry/Apache/docs/atlasTypeCreation.json http://localhost:21000/api/atlas/v2/entity

Thanks @Sarath Subramanian for your help!

[#3]

Thank you for you're help @Ashutosh Mestry and @Sarath Subramanian. And apologies for the late response.

For anyone who is interested, here's what happened when I posted the entity.

Response:

{
"mutatedEntities": {
"CREATE": [  {
"typeName": "test_entity_7",
"attributes": {
"qualifiedName": "test_entity_7_hw@Sandbox"
}
,
"guid": "01960675-149f-43da-bdb8-da79058beb51",
"status": "ACTIVE"
}
],
}
,
"guidAssignments": {
-1: "01960675-149f-43da-bdb8-da79058beb51"
}
}

GET http://127.0.0.1:21000/api/atlas/v2/entity/guid/01960675-149f-43da-bdb8-da79058beb51

{
"referredEntities": {
}
,
"entity": {
"typeName": "test_entity_7",
"attributes": {
"owner": "admin",
"test_7_2": "attr2",
"test_7_1": "attr1",
"qualifiedName": "test_entity_7_hw@Sandbox",
"name": "test_entity_7_hw",
"description": "test decription"
}
,

"guid": "01960675-149f-43da-bdb8-da79058beb51",
"status": "ACTIVE",
"createdBy": "holger_gov",
"updatedBy": "holger_gov",
"createTime": 1498267676098,
"updateTime": 1498267676098,
"version": 0,
"classifications": [],
}


}

I'm just testing in a sandbox and using Chrome apps 'Advanced REST client'. Is this why createdBy and updatedBy is set to holger_gov?

If I set the createdBy and updatedBy I still get the holger_gov:

POST http://127.0.0.1:21000/api/atlas/v2/entity

{
  "entity": {
    "typeName": "test_entity_7",
    "createdBy": "admin",
    "updatedBy": "admin",
    "attributes": {
      "description": "test decription",
      "name": "test_entity_7_hw_admin",
      "owner": "admin",
      "qualifiedName": "test_entity_7_hw_admin@Sandbox",
      "test_7_1": "attr1",
      "test_7_2": "attr2"
    },
    "guid": -1
  },
  "referredEntities": {}
}

Response

{
"mutatedEntities": {
"CREATE": [  {
"typeName": "test_entity_7",
"attributes": {
"qualifiedName": "test_entity_7_hw_admin@Sandbox"
}
,
"guid": "ed9cf696-cd76-4814-a407-9fdb8d18da3c",
"status": "ACTIVE"
}
],
}
,
"guidAssignments": {
-1: "ed9cf696-cd76-4814-a407-9fdb8d18da3c"
}
}

GET http://127.0.0.1:21000/api/atlas/v2/entity/guid/ed9cf696-cd76-4814-a407-9fdb8d18da3c

{
"referredEntities": {
}
,
"entity": {
"typeName": "test_entity_7",
"attributes": {
"owner": "admin",
"test_7_2": "attr2",
"test_7_1": "attr1",
"qualifiedName": "test_entity_7_hw_admin@Sandbox",
"name": "test_entity_7_hw_admin",
"description": "test decription"
}
,
"guid": "ed9cf696-cd76-4814-a407-9fdb8d18da3c",
"status": "ACTIVE",
"createdBy": "holger_gov",
"updatedBy": "holger_gov",
"createTime": 1498268595794,
"updateTime": 1498268595794,
"version": 0,
"classifications": [],
}
}

Also, how do I use /v2/entity/bulk? I get the following error:

{
"errorCode": "ATLAS-404-00-005",
"errorMessage": "Given instance guid {0} is invalid/not found"
}

I currently can't find a way of returning the GET for an attribute without first copying the guid when I first create it!!!

[#4]

The bulk REST APIs allow for working on several entities in a single call. They are useful when calling Atlas programmatically as this lead to less chatty interaction.

To answer the question above, the bulk GET call would be like this:

curl -g -X GET -u admin:admin "http://localhost:21000/api/atlas/v2/entity/bulk?guid=50ffa975-294d-4996-97c0-414368c67ffc&guid=fb47ab8a-b908-465d-b8f7-3ab5bbb44881"  -H 'Content-Type: application/json' > testOutput.json

After formatting the testOutput.json, you will see the details of the entity.

The bulk calls takes a list of strings, which is relatively easy to hand code. Others take more complex types, which will take more effort to hand code the json, hence easier to use via program.

Hope this helps!

[#5]

Thank you, that helps enormously!

I'm obviously doing something wrong with the GET /v2/entity/uniqueAttribute/type/{typeName}

I created an entityDefs type called test_entity_15. I then created an entity called test_entity_15.

{
   "enumDefs":[],
   "structDefs":[],
   "classificationDefs":[],
   "entityDefs":[
      {
         "superTypes":[
           "DataSet"
         ],
         "name":"test_entity_15",
         "description":"test_entity_15",
         "attributeDefs":[
            {
               "name":"test_15_1",
               "isOptional":true,
               "isUnique":true,
               "isIndexable":false,
               "typeName":"string",
               "valuesMaxCount":1,
               "cardinality":"SINGLE",
               "valuesMinCount":0
            }
         ]
         
      }
   ]
}

{
  "entity": {
    "typeName": "test_entity_15",
    "attributes": {
      "description": "test_entity_15",
      "name": "test_entity_15_1",
      "owner": "admin",
      "qualifiedName": "test_entity_15@Sandbox",
      "test_15_1": "attr1"
    },
    "guid": -1
  },
  "referredEntities": {}
}

But when I try GET http://127.0.0.1:21000/api/atlas/v2/entity/uniqueAttribute/type/test_entity_15 I get this error.

{
"errorCode": "ATLAS-400-00-013",
"errorMessage": "Type test_entity_15 with unique attribute does not exist"
}

I set "isUnique" to true, so I'm not sure what else is preventing the unique attribute!

Also, I created a JIRA due to the createdBy and updatedBy inconsistency between type and entity POSTs- https://issues.apache.org/jira/browse/ATLAS-1895

[#6]

This worked fine:

curl -g -X GET -u admin:admin "http://localhost:21000/api/atlas/v2/entity/bulk?guid=4762daa1-ac15-4b57-afbc-2ddfa063e1f5"  -H 'Content-Type: application/json'

The guid belongs to the newly created entity. Which means the entity was created successfully.

Now to retrieve the entity with uniqueAttribute it needs additional information. This call does the trick:

curl -g -X GET -u admin:admin "http://localhost:21000/api/atlas/v2/entity/uniqueAttribute/type/test_entity_15?attr:qualifiedName=test_entity_15@Sandbox" -H 'Content-Type: application/json

[#7]

I'm posting this in case anyone finds it useful.

There's now a way for metamodels to inherit values from other values, but in 0.8 you can use the qualifiedName instead of the guid, which is much better.

Type

POST http://127.0.0.1:21000/api/atlas/v2/types/typedefs

{
   "enumDefs":[],
   "structDefs":[],
   "classificationDefs":[],
   "entityDefs":[
      {
         "superTypes":[
           "DataSet"
         ],
         "name":"test_entity_18",
         "description":"test_entity_18",
         "attributeDefs":[
            {
               "name":"test_18",
               "isOptional":true,
               "isUnique":true,
               "isIndexable":false,
               "typeName":"string",
               "valuesMaxCount":1,
               "cardinality":"SINGLE",
               "valuesMinCount":0
            },
           {
               "name":"test_18_db",
               "isOptional":true,
               "isUnique":true,
               "isIndexable":false,
               "typeName":"hive_db",
               "valuesMaxCount":1,
               "cardinality":"SINGLE",
               "valuesMinCount":0
            }
         ]
         
      }
   ]
}

Entity

POST http://127.0.0.1:21000/api/atlas/v2/entity

{
  "entity": {
    "typeName": "test_entity_18",
    "createdBy": "admin",
    "updatedBy": "admin",
    "attributes": {
      "description": "test decription",
      "name": "test_entity_18",
      "owner": "admin",
      "qualifiedName": "test_entity_18",
      "test_18": "attr1",
      "test_18_db": {
        "typeName": "hive_db",
          "uniqueAttributes": {
          "qualifiedName": "default@Sandbox"
      }
      }
    },
    "guid": -1
  },
  "referredEntities": {}
}

I learnt this from here - https://issues.apache.org/jira/browse/ATLAS-1506