Manage API assets¶
Operations on API assets (specs, paths).
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, then path)
- Deleted in bottom-up order (paths, then specs, then connections)1
erDiagram
Connection ||--o{ APISpec : contains
APISpec ||--o{ APIPath : contains
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 | |
---|---|
1 2 3 4 5 6 7 8 9 10 |
|
- Retrieve the GUID for the admin role, to use later for defining the roles that can administer the connection.
- Build up the minimum request to create a connection.
- Provide a human-readable name for your connection, such as
production
ordevelopment
. - Set the type of connection to API.
- 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
, oradminUsers
must be provided. - 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
, oradminUsers
must be provided. - 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
, oradminUsers
must be provided. - Actually call Atlan to create the connection.
- Retrieve the qualifiedName for use in subsequent creation calls. (You'd probably want to do some null checking first.)
Create an API connection | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
- Retrieve the GUID for the admin role, to use later for defining the roles that can administer the connection.
- Build up the minimum request to create a connection.
- Provide a human-readable name for your connection, such as
production
ordevelopment
. - Set the type of connection to API.
- 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 ofadmin_roles
,admin_groups
, oradmin_users
must be provided. - 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 ofadmin_roles
,admin_groups
, oradmin_users
must be provided. - 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 ofadmin_roles
,admin_groups
, oradmin_users
must be provided. - Actually call Atlan to create the connection.
- Retrieve the
qualified_name
for use in subsequent creation calls. (You'd probably want to do some null checking first.)
POST /api/meta/entity/bulk | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
- The
typeName
must be exactlyConnection
. - Human-readable name for your connection, such as
production
ordevelopment
. - The
connectorName
must be exactlyapi
. - The
qualifiedName
should follow the pattern:default/api/<epoch>
, where<epoch>
is the time in milliseconds at which the connection is being created. - The
category
must beAPI
. - 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
, oradminUsers
must be provided. - 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
, oradminUsers
must be provided. - 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
, oradminUsers
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¶
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 | |
---|---|
11 12 13 14 15 16 |
|
- Build up the minimum request to create a spec.
- Provide a human-readable name for your spec.
- Provide the qualifiedName of the connection for this spec.
- Actually call Atlan to create the spec.
- Retrieve the created spec for use in subsequent creation calls. (You'd probably want to do some null checking first.)
Create an API spec | |
---|---|
17 18 19 20 21 22 |
|
- Build up the minimum request to create an spec.
- Provide a human-readable name for your spec.
- Provide the
qualified_name
of the connection for this spec. - Actually call Atlan to create the spec.
- Retrieve the created spec for use in subsequent creation calls. (You'd probably want to do some null checking first.)
POST /api/meta/entity/bulk | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
- The
typeName
must be exactlyAPISpec
. - Human-readable name for your spec.
- The
qualifiedName
should follow the pattern:default/api/<epoch>/<specName>
, wheredefault/api/<epoch>
is the qualifiedName of the connection for this spec and<specName>
is the name of this spec. - The
connectionQualifiedName
must be the exact qualifiedName of the connection for this spec. - The
connectorName
must be exactlyapi
.
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 | |
---|---|
18 19 20 21 22 |
|
- Build up the minimum request to create a path.
- 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.) - 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, orAPISpec.refByQualifiedName()
with thequalifiedName
of the spec. - Actually call Atlan to create the path.
Create an API path | |
---|---|
23 24 25 26 27 |
|
- Build up the minimum request to create an path.
- Provide the unique endpoint URI for this path.
- Provide the
qualified_name
of the API path. - Actually call Atlan to create the path.
POST /api/meta/entity/bulk | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
- The
typeName
must be exactlyAPIPath
. - Human-readable name for your path.
- The
apiPathRawURI
should be the unique endpoint URI this path represents. - The
qualifiedName
should follow the pattern:default/api/<epoch>/<specName>/<apiPathRawURI>
, wheredefault/api/<epoch>/<specName>
is the qualifiedName of the spec for this path and<apiPathRawURI>
is the unique endpoint URI the path represents. - The
connectionQualifiedName
must be the exact qualifiedName of the connection for this path. - The
connectorName
must be exactlyapi
. - The spec in which this path exists is embedded in the
apiSpec
attribute. - The
typeName
for this embedded reference must beAPISpec
. - 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.
Available relationships¶
Every level of the API structure is an Asset
, and can therefore be related to the following other assets.
title: Asset management overview description: Overview of asset-related entities and their relationships, including glossary terms, links, READMEs, and processes.
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.
-
Although if you want to delete everything in a connection, your better avenue is the packaged connection delete utility in the UI. ↩