Skip to main content

API 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)1

Asset structure​

Connection​

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.

Create an API connection
String adminRoleGuid = client.getRoleCache().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(client); // (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 GUIDs of the workspace roles. 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 names of the groups. 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 usernames of the users. At least one of adminRoles, adminGroups, or adminUsers must be provided.
  8. Actually call Atlan to create the connection. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  9. Retrieve the qualifiedName for use in subsequent creation calls. (You'd probably want to do some null checking first.)

APISpec​

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

Create an API spec
APISpec apiSpec = APISpec.creator( // (1)
        "api-spec", // (2)
        connectionQualifiedName) // (3)
    .build();
AssetMutationResponse response = apiSpec.save(client); // (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. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  5. Retrieve the created spec for use in subsequent creation calls. (You'd probably want to do some null checking first.)

APIPath​

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.

Create an API path
APIPath apiPath = APIPath.creator( // (1)
        "/api/path", // (2)
        apiSpec) // (3)
    .build();
AssetMutationResponse response = apiPath.save(client); // (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 didn't 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. Because this operation will persist the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.

APIObject​

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.

Create an API object
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.)

APIQuery​

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.

Create an API query
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.)

APIField​

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​

Create an API field inside an API Object
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.

APIField inside APIQuery​

Create an API field inside an API Query
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.

Available relationships​

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

Footnotes​

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

Was this page helpful?