Manage API assets

Operations on API assets (specs, paths, objects, queries, fields).

Example OpenAPI crawler

For a jump-start, read more about an example for crawling OpenAPI specifications, or grab the code from: atlanhq/atlan-java-samples

In general, these should be:

• Created in top-down order (connection, then spec/object/query, then path/field)
• Deleted in bottom-up order (paths/fields, then specs/objects/queries, then connections)¹

erDiagram
  Connection ||--o{ APISpec : contains
  APISpec ||--o{ APIPath : contains
  Connection ||--o{ APIObject : contains
  Connection ||--o{ APIQuery : contains
  APIObject ||--o{ APIField : contains
  APIQuery ||--o{ APIField : contains
  APIObject o|..o{ APIField : refers
  APIObject o|..o{ APIQuery : refers

Asset structure

Connection

2.0.0 1.0.0

An API connection requires a name and qualifiedName. For creation, specific settings are also required to distinguish it as an API connection rather than another type of connection. In addition, at least one of adminRoles, adminGroups, or adminUsers must be provided.

Java Python Raw REST API

String adminRoleGuid = RoleCache.getIdForName("$admin"); // (1)
Connection connection = Connection.creator( // (2)
        "api-connection", // (3)
        AtlanConnectorType.API, // (4)
        List.of(adminRoleGuid), // (5)
        List.of("group2"), // (6)
        List.of("jsmith")) // (7)
    .build();
AssetMutationResponse response = connection.save(); // (8)
String connectionQualifiedName = response.getCreatedAssets().get(0).getQualifiedName(); // (9)

1. Retrieve the GUID for the admin role, to use later for defining the roles that can administer the connection.
2. Build up the minimum request to create a connection.
3. Provide a human-readable name for your connection, such as production or development.
4. Set the type of connection to API.
5. List the workspace roles that should be able to administer the connection (or null if none). All users with that workspace role (current and future) will be administrators of the connection. Note that the values here need to be the GUID(s) of the workspace role(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
6. List the group names that can administer this connection (or null if none). All users within that group (current and future) will be administrators of the connection. Note that the values here are the name(s) of the group(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
7. List the user names that can administer this connection (or null if none). Note that the values here are the username(s) of the user(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
8. Actually call Atlan to create the connection.
9. Retrieve the qualifiedName for use in subsequent creation calls. (You'd probably want to do some null checking first.)

from pyatlan.cache.role_cache import RoleCache
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import Connection, APISpec, APIPath, APIObject, APIQuery, APIField
from pyatlan.model.enums import AtlanConnectorType, APIQueryParamTypeEnum

admin_role_guid = RoleCache.get_id_for_name("$admin") # (1)
connection = Connection.creator( # (2)
    name = "api-connection", # (3)
    connector_type = AtlanConnectorType.API, # (4)
    admin_roles = [admin_role_guid], # (5)
    admin_groups = ["group2"], # (6)
    admin_users = ["jsmith"]) # (7)
) 

response = client.asset.save(connection) # (8)
connection_qualified_name = response.assets_created(asset_type=Connection)[0].qualified_name # (9)

1. Retrieve the GUID for the admin role, to use later for defining the roles that can administer the connection.
2. Build up the minimum request to create a connection.
3. Provide a human-readable name for your connection, such as production or development.
4. Set the type of connection to API.
5. List the workspace roles that should be able to administer the connection (or None if none). All users with that workspace role (current and future) will be administrators of the connection. Note that the values here need to be the GUID(s) of the workspace role(s). At least one of admin_roles, admin_groups, or admin_users must be provided.
6. List the group names that can administer this connection (or None if none). All users within that group (current and future) will be administrators of the connection. Note that the values here are the name(s) of the group(s). At least one of admin_roles, admin_groups, or admin_users must be provided.
7. List the user names that can administer this connection (or None if none). Note that the values here are the username(s) of the user(s). At least one of admin_roles, admin_groups, or admin_users must be provided.
8. Actually call Atlan to create the connection.
9. Retrieve the qualified_name for use in subsequent creation calls. (You'd probably want to do some null checking first.)

{
  "entities": [
    {
      "typeName": "Connection", // (1)
      "attributes": {
        "name": "api-connection", // (2)
        "connectorName": "api", // (3)
        "qualifiedName": "default/api/123456789", // (4)
        "category": "API", // (5)
        "adminRoles": [ // (6)
          "e7ae0295-c60a-469a-bd2c-fb903943aa02"
        ],
        "adminGroups": [ // (7)
          "group2"
        ],
        "adminUsers": [ // (8)
          "jsmith"
        ]
      }
    }
  ]
}

1. The typeName must be exactly Connection.
2. Human-readable name for your connection, such as production or development.
3. The connectorName must be exactly api.
4. The qualifiedName should follow the pattern: default/api/<epoch>, where <epoch> is the time in milliseconds at which the connection is being created.
5. The category must be API.
6. List any workspace roles that can administer this connection. All users with that workspace role (current and future) will be administrators of the connection. Note that the values here need to be the GUID(s) of the workspace role(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
7. List any groups that can administer this connection. All users within that group (current and future) will be administrators of the connection. Note that the values here are the name(s) of the group(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.
8. List any users that can administer this connection. Note that the values here are the username(s) of the user(s). At least one of adminRoles, adminGroups, or adminUsers must be provided.

Access policies

Atlan creates the policies that grant access to a connection, including the ability to retrieve the connection and to create assets within it, asynchronously. It can take several seconds (even up to approximately 30 seconds) before these are in place after creating the connection.

You may therefore need to wait before you'll be able to create the assets below within the connection.

To confirm access, retrieve the connection after it has been created. The SDKs' retry loops will automatically retry until the connection can be successfully retrieved. At that point, your API token has permission to create the other assets.

Note: if you are reusing an existing connection rather than creating one via your API token, you must give your API token a persona that has access to that connection. Otherwise all attempts to create, read, update, or delete assets within that connection will fail due to a lack of permissions.

APISpec

2.0.0 1.0.0

An API spec requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the spec.

Java Python Raw REST API

APISpec apiSpec = APISpec.creator( // (1)
        "api-spec", // (2)
        connectionQualifiedName) // (3)
    .build();
AssetMutationResponse response = apiSpec.save(); // (4)
apiSpec = response.getResult(apiSpec); // (5)

1. Build up the minimum request to create a spec.
2. Provide a human-readable name for your spec.
3. Provide the qualifiedName of the connection for this spec.
4. Actually call Atlan to create the spec.
5. Retrieve the created spec for use in subsequent creation calls. (You'd probably want to do some null checking first.)

apiSpec = APISpec.creator( # (1)
    name = "api-spec", # (2)
    connection_qualified_name = connection_qualified_name # (3)
)
response = client.asset.save(apiSpec) # (4)
spec_qualified_name = response.assets_created(asset_type=APISpec)[0].qualified_name # (5)

1. Build up the minimum request to create an spec.
2. Provide a human-readable name for your spec.
3. Provide the qualified_name of the connection for this spec.
4. Actually call Atlan to create the spec.
5. Retrieve the created spec for use in subsequent creation calls. (You'd probably want to do some null checking first.)

{
  "entities": [
    {
      "typeName": "APISpec", // (1)
      "attributes": {
        "name": "api-spec", // (2)
        "qualifiedName": "default/api/123456789/api-spec", // (3)
        "connectionQualifiedName": "default/api/123456789", // (4)
        "connectorName": "api" // (5)
      }
    }
  ]
}

1. The typeName must be exactly APISpec.
2. Human-readable name for your spec.
3. The qualifiedName should follow the pattern: default/api/<epoch>/<specName>, where default/api/<epoch> is the qualifiedName of the connection for this spec and <specName> is the name of this spec.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this spec.
5. The connectorName must be exactly api.

APIPath

2.0.0 1.0.0

An API path requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the path and the apiSpec the path is in. If the name of your path does no give the URI of the endpoint it represents, be sure to also specify the apiPathRawURI.

Java Python Raw REST API

APIPath apiPath = APIPath.creator( // (1)
        "/api/path", // (2)
        apiSpec) // (3)
    .build();
AssetMutationResponse response = apiPath.save(); // (4)

1. Build up the minimum request to create a path.
2. Provide the unique endpoint URI for this path. (The SDK will also use this by default as the name for the path. If you want a different name, simply add a .name() call onto the builder with your preferred name.)
3. Provide the spec for this path. If you did not already have the object, you could also use APISpec.refByGuid() with the GUID of the spec, or APISpec.refByQualifiedName() with the qualifiedName of the spec.
4. Actually call Atlan to create the path.

apiPath = APIPath.creator( # (1)
    path_raw_uri = "/api/path", # (2)
    spec_qualified_name = spec_qualified_name # (3)
)
response = client.asset.save(apiPath) # (4)

1. Build up the minimum request to create an path.
2. Provide the unique endpoint URI for this path.
3. Provide the qualified_name of the API path.
4. Actually call Atlan to create the path.

{
  "entities": [
    {
      "typeName": "APIPath", // (1)
      "attributes": {
        "name": "/api/path", // (2)
        "apiPathRawURI": "/api/path", // (3)
        "qualifiedName": "default/api/123456789/api-spec/api/path", // (4)
        "connectionQualifiedName": "default/api/123456789", // (5)
        "connectorName": "api", // (6)
        "apiSpec": { // (7)
          "typeName": "APISpec", // (8)
          "uniqueAttributes": { // (9)
            "qualifiedName": "default/api/123456789/api-spec"
          }
        }
      }
    }
  ]
}

1. The typeName must be exactly APIPath.
2. Human-readable name for your path.
3. The apiPathRawURI should be the unique endpoint URI this path represents.
4. The qualifiedName should follow the pattern: default/api/<epoch>/<specName>/<apiPathRawURI>, where default/api/<epoch>/<specName> is the qualifiedName of the spec for this path and <apiPathRawURI> is the unique endpoint URI the path represents.
5. The connectionQualifiedName must be the exact qualifiedName of the connection for this path.
6. The connectorName must be exactly api.
7. The spec in which this path exists is embedded in the apiSpec attribute.
8. The typeName for this embedded reference must be APISpec.
9. To complete the reference, you must include a uniqueAttributes object with the qualifiedName of the spec. Note: the spec must already exist in Atlan before creating the path.

APIObject

2.5.3

An API object requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the object. Optionally, you can also provide the count of API field that exists in the object as apiFieldCount.

Python Raw REST API

apiObject = APIObject.creator( # (1)
    name = "api-object", # (2)
    connection_qualified_name = connection_qualified_name, # (3)
    api_field_count = 2 # (4)
)
response = client.asset.save(apiObject) # (5)
object_qualified_name = response.assets_created(asset_type=APIObject)[0].qualified_name # (6)

1. Build up the minimum request to create an object.
2. Provide a human-readable name for your object.
3. Provide the qualified_name of the connection for this object.
4. Provide the count of fields that exist in the object. Use None if no field exists in this object.
5. Actually call Atlan to create the object.
6. Retrieve the created object for use in subsequent creation calls. (You'd probably want to do some null checking first.)

{
  "entities": [
    {
      "typeName": "APIObject", // (1)
      "attributes": {
        "name": "api-object", // (2)
        "qualifiedName": "default/api/123456789/api-object", // (3)
        "connectionQualifiedName": "default/api/123456789", // (4)
        "connectorName": "api", // (5)
        "apiFieldCount": 2 // (6)
      }
    }
  ]
}

1. The typeName must be exactly APIObject.
2. Human-readable name for your object.
3. The qualifiedName should follow the pattern: default/api/<epoch>/<objectName>, where default/api/<epoch> is the qualifiedName of the connection for this object and <objectName> is the name of this object.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this object.
5. The connectorName must be exactly api.
6. The apiFieldCount should be the count of the fields present in the object. This is not a required attribute and can be excluded.

APIQuery

2.5.3

An API query requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the query.

Optionally, you can provide other attribute which enrich the query asset. Like apiInputFieldCount to store the count of input API fields in the query. apiQueryOutputType and apiQueryOutputTypeSecondary to store the query output types. If the query refers to an object in its output, it requires apiIsObjectReference and apiObjectQualifiedName to be populated.

Python Raw REST API

apiQuery = APIQuery.creator( # (1)
    name = "api-query", # (2)
    connection_qualified_name = connection_qualified_name, # (3)
    api_input_field_count = 2, # (4)
    api_query_output_type="api-object-ref", # (5)
    api_query_output_type_secondary="Object", # (6)
    is_object_reference=True, # (7)
    reference_api_object_qualified_name="default/api/123456789/api-object-ref" # (8)
)
response = client.asset.save(apiQuery) # (9)
query_qualified_name = response.assets_created(asset_type=APIQuery)[0].qualified_name # (10)

1. Build up the minimum request to create a query.
2. Provide a human-readable name for your query.
3. Provide the qualified_name of the connection for this query.
4. Provide the count of input fields that exist in the query. Use None if no input field exists in this query.
5. Provide the primary type for the output of the query. E.g.: If Object/api-obj-ref, then api-obj-ref is primary.
6. Provide the secondary type for the output of the query. E.g.: If Object/api-obj-ref, then Object is secondary.
7. If the Output of the query refers to an object make it True or else False.
8. If is_object_reference is True, provide the qualified name of the object this query refers to in output. Or None.
9. Actually call Atlan to create the query.
10. Retrieve the created query for use in subsequent creation calls. (You'd probably want to do some null checking first.)

{
  "entities": [
    {
      "typeName": "APIQuery", // (1)
      "attributes": {
        "name": "api-query", // (2)
        "qualifiedName": "default/api/123456789/api-query", // (3)
        "connectionQualifiedName": "default/api/123456789", // (4)
        "connectorName": "api", // (5)
        "apiInputFieldCount": 2, // (6)
        "apiQueryOutputType": "api-object-ref", // (7)
        "apiQueryOutputTypeSecondary": "Object", // (8)
        "apiIsObjectReference": true, // (9)
        "apiObjectQualifiedName": "default/api/123456789/api-object-ref" // (10)
      }
    }
  ]
}

1. The typeName must be exactly APIQuery.
2. Human-readable name for your query.
3. The qualifiedName should follow the pattern: default/api/<epoch>/<queryName>, where default/api/<epoch> is the qualifiedName of the connection for this query and <queryName> is the name of this query.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this query.
5. The connectorName must be exactly api.
6. The apiInputFieldCount should be the count of the input fields present in the object. For no input fields, remove the attribute from the request.
7. The apiQueryOutputType is the primary type for the output of the query. E.g.: If Object/api-obj-ref, then api-obj-ref is primary.
8. The apiQueryOutputTypeSecondary is the secondary type for the output of the query. E.g.: If Object/api-obj-ref, then Object is secondary.
9. The apiIsObjectReference should be true when the query refers to an object in its output.
10. The apiObjectQualifiedName is the qualified name of the object this query refers to in its output. Remove attribute when apiIsObjectReference is false.

APIField

2.5.3

An API field requires a name and a qualifiedName. For creation, you also need to specify the connectionQualifiedName of the connection for the field and either the apiObject or the apiQuery the field is in.

Optionally, you can provide other attribute which enrich the field asset. Like apiFieldType and apiFieldTypeSecondary to store the field types. If the field refers to an object, it requires apiIsObjectReference and apiObjectQualifiedName to be populated.

APIField inside APIObject

Python Raw REST API

apifield = APIField.creator( # (1)
    name = "api-field", # (2)
    parent_api_object_qualified_name = object_qualified_name, # (3)
    parent_api_query_qualified_name = None, # (4)
    connection_qualified_name = connection_qualified_name, # (5)
    api_field_type="api-object-ref", # (6)
    api_field_type_secondary="Object", # (7)
    is_api_object_reference=True, # (8)
    reference_api_object_qualified_name="default/api/123456789/api-object-ref", # (9)
    api_query_param_type=None # (10)
)
response = client.asset.save(apifield) # (11)

1. Build up the minimum request to create a field.
2. Provide the human-readable name for this field.
3. Provide the qualified_name of the API object, this field exists in.
4. None for when this object exists in an object and not in a query.
5. Provide the qualified_name of the connection for this field.
6. Provide the primary type of the field.
7. Provide the secondary type of the field.
8. True when the field refers to an object. Else False.
9. Provide the qualified_name of the API object this field refers to. None when is_api_object_reference is False.
10. None when field is inside an object. Holds Enum value when inside a query as input.
11. Actually call Atlan to create the path.

{
  "entities": [
    {
      "typeName": "APIField", // (1)
      "attributes": {
        "name": "api-field", // (2)
        "qualifiedName": "default/api/123456789/api-object/api-field", // (3)
        "connectionQualifiedName": "default/api/123456789", // (4)
        "connectorName": "api", // (5)
        "apiFieldType": "String", // (6)
        "apiFieldTypeSecondary": "String", // (7)
        "apiObject": { // (8)
          "typeName": "APIObject", // (9)
          "uniqueAttributes": { // (10)
            "qualifiedName": "default/api/123456789/api-object"
          }
        },
        "apiIsObjectReference": true, // (11)
        "apiObjectQualifiedName": "default/api/123456789/api-object-ref" // (12)
      }
    }
  ]
}

1. The typeName must be exactly APIField.
2. Human-readable name for your field.
3. The qualifiedName should follow the pattern: default/api/<epoch>/<objectName>/<fieldName>, where default/api/<epoch>/<objectName> is the qualifiedName of the object for this field and <fieldName> is the human-readable name of the field.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this field.
5. The connectorName must be exactly api.
6. The apiFieldType is the primary type of the field.
7. The apiFieldTypeSecondary is the secondary type of the field.
8. The object in which this field exists is embedded in the apiObject attribute.
9. The typeName for this embedded reference must be APIObject.
10. To complete the reference, you must include a uniqueAttributes object with the qualifiedName of the object. Note: the object must already exist in Atlan before creating the path.
11. The apiIsObjectReference should be true when this field refers to an object.
12. The apiObjectQualifiedName should incldue the reference object qualified_name when apiIsObjectReference is true.

APIField inside APIQuery

Python Raw REST API

apifield = APIField.creator( # (1)
    name = "api-field", # (2)
    parent_api_object_qualified_name = None, # (3)
    parent_api_query_qualified_name = query_qualified_name, # (4)
    connection_qualified_name = connection_qualified_name, # (5)
    api_field_type="api-object-ref", # (6)
    api_field_type_secondary="Object", # (7)
    is_api_object_reference=True, # (8)
    reference_api_object_qualified_name="default/api/123456789/api-object-ref", # (9)
    api_query_param_type=APIQueryParamTypeEnum.INPUT # (10)
)
response = client.asset.save(apifield) # (11)

1. Build up the minimum request to create a field.
2. Provide the human-readable name for this field.
3. None for when this object exists in a query and not in an object.
4. Provide the qualified_name of the API query, this field exists in.
5. Provide the qualified_name of the connection for this field.
6. Provide the primary type of the field.
7. Provide the secondary type of the field.
8. True when the field refers to an object. Else False.
9. Provide the qualified_name of the API object this field refers to. None when is_api_object_reference is False.
10. Provide the enum value INPUT, if the field is an input to the query.
11. Actually call Atlan to create the path.

{
  "entities": [
    {
      "typeName": "APIField", // (1)
      "attributes": {
        "name": "api-field", // (2)
        "qualifiedName": "default/api/123456789/api-query/api-field", // (3)
        "connectionQualifiedName": "default/api/123456789", // (4)
        "connectorName": "api", // (5)
        "apiFieldType": "String", // (6)
        "apiFieldTypeSecondary": "String", // (7)
        "apiQuery": { // (8)
          "typeName": "APIQuery", // (9)
          "uniqueAttributes": { // (10)
            "qualifiedName": "default/api/123456789/api-query"
          }
        },
        "apiIsObjectReference": true, // (11)
        "apiObjectQualifiedName": "default/api/123456789/api-object-ref", // (12)
        "apiQueryParamType": "Input" // (13)
      }
    }
  ]
}

1. The typeName must be exactly APIField.
2. Human-readable name for your field.
3. The qualifiedName should follow the pattern: default/api/<epoch>/<queryName>/<fieldName>, where default/api/<epoch>/<queryName> is the qualifiedName of the query for which this field is an input and <fieldName> is the human-readable name of the field.
4. The connectionQualifiedName must be the exact qualifiedName of the connection for this field.
5. The connectorName must be exactly api.
6. The apiFieldType is the primary type of the field.
7. The apiFieldTypeSecondary is the secondary type of the field.
8. The query in which this field exists is embedded in the apiQuery attribute.
9. The typeName for this embedded reference must be APIQuery.
10. To complete the reference, you must include a uniqueAttributes object with the qualifiedName of the query. Note: the object must already exist in Atlan before creating the path.
11. The apiIsObjectReference should be true when this field refers to an object.
12. The apiObjectQualifiedName should incldue the reference object qualified_name when apiIsObjectReference is true.
13. The apiQueryParamType should be present when the field is an input to a query. The value must exactly be "Input".

Available relationships

Every level of the API structure is an Asset, and can therefore be related to the following other assets.

erDiagram
  Asset }o--o{ AtlasGlossaryTerm : meanings
  Asset ||--o{ Link : links
  Asset ||--o| Readme : readme
  Asset }o--o{ Process : inputToProcesses
  Asset }o--o{ Process : outputFromProcesses

AtlasGlossaryTerm

A glossary term provides meaning to an asset. The link terms to assets snippet provides more detail on setting this relationship.

Link

A link provides additional context to an asset, by providing a URL to additional information.

Readme

A README provides rich documentation for an asset. The add asset READMEs snippet provides more detail on setting this relationship.

Process

A process provides lineage information for an asset. An asset can be both an input and an output for one or more processes. The lineage snippets provide more detail on creating and working with lineage.

---

1. Although if you want to delete everything in a connection, your better avenue is the packaged connection delete utility in the UI. ↩

---