Explore the available LeanIX APIs and how to best utilize them to meet your needs.
There are many options for creating, reading, updating, deleting data from and to LeanIX. Many of these options overlap which can be utilized in multiple use cases. This guide might suggest that the Integration API is the best choice for a particular use case. However, it does not suggest that you cannot achieve similar results using GraphQL for example.
Prior to taking a look at available technical tools, it is useful to have basic knowledge of the LeanIX Meta-Model. For an introduction to the Meta-Model please check out the documentation page.
To see the full list of APIs and details on how to use them please see the Available API section.
We have a built-in editor for many of these tools. To access them go to your Administration area click the user icon on the top right corner and select Administration:
To access GraphiQL, Webhooks, and the Integration API built-in editors see the below:
Integration API: Import/Export Data
About the API
The Integration API is extremely flexible and powerful. One of the main reasons is at the heart it is driven by a generic LeanIX Data Interchange Format (LDIF). This imparts many benefits, which include but are not limited to:
Complexity is minimized as developers no longer have to understand the LeanIX Meta-Model
No longer have to map logic inside a code
The Integration API can be utilized to build an integration between LeanIX and another vendor system. One major advantage is that the CRUD operations for any inbound (other vendor system to LeanIX ) is managed within LeanIX, which removes a great deal of complexity.
The ability to define variables, exceptions, use JUEL expressions to extract or import only particular values that meet what you define, is powerful.
In addition, there are other benefits imparted by the Integration API that are not specifically related to the LDIF structure:
Configuration for LeanIX is contained in every connector
Integration now possible even if the external system does not allow direct access
No need for a direct REST connection
Flexible error handling, no failure due to a single or even multiple data issues. Data that does not meet the requirements, is simply ignored
Cross-cutting concerns are part of the API and in each connector
It can also be used to import/export from your workspace. This can be useful in cases where the built in import/export functionality doesn't have the capability that is required. An example of such a case are attributes which exist on relations. At this time it is not possible to mass update attributes on relations using the UI.
The flexibility of the Integration API shines in more complex cases such as: when the data from the source system is not in a "clean" state. In this case the Integration API would be a good option due to its error handling capabilities. It is flexible and any errors can be ignored (this is not the case with built-in Inventory import/export or GraphQL). In addition, the Integration API supports the use of JUEL/RegEx which imparts the ability to transform the source data, for example you can utilize .sum() to add up costs and then file that into a cost attribute in LeanIX. Please see the Integration API documentation for detailed information.
- Build an integration with an external system for example ITSM Integration.
- Make one-off updates to your workspace which you would normally use in the import/export functionality via UI.
- Merge two or more separate physical workspaces. This might be necessary in case of an acquisition or merger.
GraphQL: insights from data
GraphQL allows you to query the data on your Fact Sheets as well as mutate (e.g update, delete) the data. In addition, GraphQL is utilized to create custom reports, specifically to pull data from the workspace and present it using charts and other graphics.
Use the built-in GraphiQL Tool available within your LeanIX Administration area when you need answers to your Fact Sheet data. In addition, the GraphiQL Tool allows you to interactively develop and test queries and mutations. Which later can be utilized in scripts to automate work or custom reports.
Once in the Administration area, from the "Developers" tab select "Tools" then select GraphiQL.
In order to get a fundamental understanding of GraphQL. You need to understand two main ideas, queries and mutations.
A query allows you to formulate precisely what arguments to return and what filters to apply.
A mutation allows you to apply patches (updates) or delete objects. Again, you can combine patches or define precisely what arguments to return.
Benefits of GraphQL
|Developers can summarize multiple API calls in one. This allows them to focus on the business logic instead of combining call results and handling different transactions.|
|In particular for large reports or analytics, GraphQL increases performance dramatically. Now, you can transfer exactly the attributes you require via the network, with no extra latency. Furthermore, GraphQL aligns perfectly with an underlying Graph Database to answer queries that span multiple relations, e.g. Evaluating Technology Risk Transitively.|
|The GraphQL schema is strongly typed. This is an asset as the strong typing defines that the API is largely self documented. You can see what the immediate response to the query will be.|
|Since everything in GraphQL is schema driven, extending it won't be a problem if a new field is added. This won't affect the existing fields and also GraphQL introduces @deprecated annotation to deprecate fields. This eliminates the need for versioning the API.|
|Export of Applications with specific attributes|
|Export of specific relationships between two Fact Sheet types|
|Export of external ID's for all Applications|
|Update specific attributes on specific Fact Sheets|
The best cases for utilizing the GraphiQL Tool:
Focus on queries, and or mutations that are one-off in nature or for which you do not need to regularly (e.g monthly, weekly) get up-to-date information.
Where you need to pull relatively simple information. While complex queries are very much possible to an extent, there are other alternatives such as the Integration API which you might find an easier and flexible choice.
GraphQL features heavily in custom reports because it is used to pull information from the workspace which is presented using charts and other graphics.
Endpoints and scripts
The GraphQL API endpoint can be utilized to create scripts and build a REST API. It might be best to review the functionality available within the Integration API because it is expressly created to resolve or minimize several challenges developers face when building an integration.
Please see the GraphQL in 10 minutes documentation for more detailed information on GraphQL and GraphQL Advanced.
The public LeanIX GitHub contains many scripts that utilize GraphQL. Some of the scripts are listed below:
More about GraphQL: reporting:
Webhooks: Event-Driven Information
Webhooks allow an application in LeanIX to supply other applications with real-time information. Which allows webhooks to furnish data to other applications as it occurs. In contrast to traditional APIs where to get up-to-date information, the app would need to send a request. This makes webhooks an efficient choice for providers and consumers.
What are events? Events in this context are actions that end users take within an application. Some examples are entering a response within an attribute such as the Description field, creating a new Fact Sheet, or even logging into LeanIX. When you need an event-driven integration, webhooks are the answer. One such use case is when you need to trigger notifications to be sent based on when a Fact Sheet (or an attribute/field on the Fact Sheet(s)) is updated, created, or deleted**.
Many systems offer a built-in user interface to allow end-users to easily create simple webhooks. LeanIX offers a user interface within the Administration area of your workspace in addition to an API endpoint.
To get an introduction to webhooks please see the "Getting Started Webhooks" documentation.
Build a Slack Bot using webhooks.
The technical suitability is updated on a Fact Sheet, this event can trigger a tag to be automatically added to the Fact Sheet. Please see the Azure Function Tutorial: TIME tutorial for an example of this implemented with Webhooks and Azure function.
Utilizing the responses from a LeanIX survey to calculate a particular score and the score can be automatically set to be associated with a Fact Sheet.
Metrics: Data Over Time
With Metrics you can store time series data in LeanIX and create interactive charts to display the data. In addition, the data can be linked to Fact Sheets presented on Dashboard or be displayed within the Reports area.
Metrics consist of several objects including measurements. Measurements contain data-points stored over time, which are related to the same topic. Each data-point is stored for a specific moment and has one or more values for that instance of time.
Metrics are very specific to cases when there are data points that are time based. One such example is when expenses or other costs need to be understood on the basis of time.
For more information please see Getting Started with Metrics.
LeanIX is built with a Microservices architecture, with different services and API endpoints. Below is a list of all public APIs. For each entry, the main resources, endpoint URL and links to Swagger API References are listed.
Your Endpoint Base URL (often referred to with the variable 'base_url' in our public scripts and tutorial examples) will vary depending the domain of your workspace. The simplest way to determine your endpoint base URL is to pull it directly from the URL displayed in your browser when navigating your workspace "https://...leanix.net".
If my main dashboard URL were https://MyCompany.leanix.net/MyCompanyWorkspace/dashboard/184710fa-4272-4163-ba99-ddfcb46eaf4a, my endpoint URL would be https://MyCompany.leanix.net
To access the APIs as well as to see what your workspace instance is. Select About LeanIX and then Browse API:
Pathfinder API: Inventory
Information about used applications, technologies, projects and more objects can be stored in the IT Inventory of LeanIX. LeanIX provides a Meta-Model called "Fact Sheets" out of the box. Via Pathfinder API you can interact with this Meta-Model.
|All Fact Sheets Types: Applications, IT Components, Projects, ...|
<base_url>/services/pathfinder/v1, e.g. https://app.leanix.net/services/pathfinder/v1
MTM API: Authentication & User Management
MTM stands for Multi-Tenancy Manager. It is a central service of LeanIX to manage workspaces and user accounts. It also provides OAuth2 endpoints for authentication of users.
Not all resources with the MTM API are available to ADMINs. There are endpoints that are visible within the Swagger documentation which are only available to LeanIX employees. Such are marked as "Restricted to LeanIX internal use only." in the endpoint description.
Below is a list of the resources available to customers. Please note that this is not the exhaustive list.
|apiTokens:Manage api tokens|
|notificationsBatches:User notification batches|
|technicalUser:Manage technical user|
Admins role cannot see all API Tokens in a workspace. API tokens are personalized identification tokens specific to a user. The user's credentials are part of the encryption of the token. This is also what binds API-tokens to a specific user, any updates performed by the API token will be performed in the user's name. It is by design that API tokens are not visible to other users, even Admins. If you have shared services (Integrations, webhooks, etc.) which use API-tokens which you would like multiple people to have access to please make use of the technical user functionality. The technical user functionality is designed with that use case in mind.
Who can see what:
- User X is only able to see their own API-tokens.
- Even the SUPERADMIN support user can only see our own tokens.
Additionally, the moment an Admin archived a user all issued API-tokens for that user become invalid immediately.
We have configured it in such a way that the tokens will expire after a specific time period due to inactivity.
Please see the highlighted image below for the specific endpoints available to ADMINs under workspaces:Manage workspaces:
<base_url>/services/mtm/v1, e.g. https://app.leanix.net/services/mtm/v1
Please do not use API tokens if you have central management as a requirement. We offer Technical users for such use cases. Technical user tokens can be generated by an administrator and will be manageable and visible by all administrators in our UI.
For user management, please always use the endpoint:
USA customers please utilize:
Also, see User Management
Webhooks API: Event Subscriptions
Webhooks allows you to receive information about events as they happen near real-time in LeanIX. You can then extend, customize, and integrate LeanIX with your own extensions or even with other applications.
<base_url>/services/webhooks/v1, e.g. https://app.leanix.net/services/webhooks/v1**
Metrics API: Real-Time Data
The Metrics add-on allows you to store time-series data in LeanIX. This data can come from various sources which are relevant to Business, Development or Operations.
<base_url>/services/metrics/v1, e.g. https://app.leanix.net/services/metrics/v1
Poll API: Custom Surveys
With the Survey add-on, admins can design own questionnaires in LeanIX which they send out to get the answers from users. The results of the surveys are displayed in context of LeanIX and can be accessed via API.
Integration API: Import/Export Data and Build Integrations
The Integration API provides the ability to import/export data using a generic LeanIX Data Interchange Format (LDIF). LDIF is a JSON format with a very simple structure described in the following sections. In addition, building integrations between LeanIX and other vendor systems is simplified using the Integration API. One of the reason is because all mapping and processing of the incoming and outgoing data is done using "Data Processors" that are configured behind the API. For detailed information including use cases please see Integration API.