Python API
Interacting with XPipe from Python
Introduction
The XPipe Python API is a Python client for the XPipe HTTP API. It is essentially a wrapper for the raw HTTP API and intended to make working with it more convenient. If you are not that comfortable with Python, the API can also be used in other languages via a simple HTTP client library that supports exchanging json requests.
You can find the source code at https://github.com/xpipe-io/xpipe-python-api and the code of the samples used on this page at https://github.com/xpipe-io/xpipe-python-api/tree/master/samples.
The primary use cases for the Python API are:
- Automatic import and migration of lots of servers from other sources where configuring them manually it would take too much time, e.g. if you want to migrate ~1000 servers to XPipe. There are only limited migration tools for other tools, so using the API makes sense, especially when it comes to also importing secrets.
- Automated management of a fleet of servers. For example, upgrading or configuring a tool on all servers. Especially when the workflow is more than just running a command, e.g., different control flows based on the server configuration. Furthermore, this allows for an automated aggregation of results to check whether the task completed successfully on all systems.
Installation
python3 -m pip install xpipe_apiConnecting to the XPipe application
To start out, you need to enable the API access in the XPipe settings. You can find that under Settings -> HTTP API. For only local API access, you don't need to worry about the API key in the settings menu.
from xpipe_api import Client
# By default, Client() will read an access key from the file xpipe_auth on the local filesystem
# and talk to the XPipe HTTP server on localhost.
client = Client()
# If you want to connect to a PTB build of XPipe, you have to configure the client with that information
# as the PTB releases use a different port
client = Client(ptb=True)
# To connect to a remote instance with an API key
# To make an XPipe instance allow external connections, i.e. not on localhost,
# you have to enable the "Allow external API requests" setting in the API settings menu
client = Client(token="foo", base_url = "http://servername:21721")There's also an async version of the client that can be accessed as AsyncClient. All calls are run asynchronously with that client. This page will only cover the sync client though.
import asyncio
from xpipe_api import AsyncClient
async def main():
client = AsyncClient()
# Do your stuff async
if __name__ == "__main__":
asyncio.run(main())Stores and connections
In the context of the API, XPipe refers to any kind of connection, identity, script, and others as a store. This just refers to the fact that those entries store json configuration data and some metadata.
In general, the process of adding, editing, and removing stores is the same, regardless of the type of store. Only the json data and the capabilities of the store will differ.
Querying connections
A store reference is just a UUID string. You can query one or multiple existing stores that are stored in XPipe based on various filters.
from xpipe_api import Client
client = Client()
# store_query accepts glob-based filters on the category, store name, and store type
# Find all stores in the default category and all its subcategories
stores = client.store_query(categories="all connections/default**")
# Find all stores in the subcategories of default
stores = client.store_query(categories="all connections/default/**")
# Find all stores in the default category without any subcategories
stores = client.store_query(categories="all connections/default")
# Find all top level stores in the default category
stores = client.store_query(categories="all connections/default", stores="*")
# Find all stores in the default category, including any children
stores = client.store_query(categories="all connections/default", stores="**")
# Find all SSH config stores on the local machine
stores = client.store_query(categories="all connections/default", stores="Local Machine/SSH user config/*")
# Find only ssh config host stores in the "MyCategory" category that has the word "MyCompany" in its name
# - Searching for strings is case-insensitive here
# - This will not include subcategories of "MyCategory"
# - You can find all the available store type names by just querying all stores and taking a look add the individual type names of the stores.
stores = client.store_query(categories="**/MyCategory", types="sshConfigHost", stores="*MyCompany*")
# Query a specific store by name in a category
# This will only return one element, so we can just access that
store = client.store_query(categories="**/MyCategory", stores="MyConnectionName")[0]
# Query the local machine connection
store = client.store_query(stores="Local Machine")[0]
# A store reference is just a UUID string, so you can also specify it fixed
store = "f0ec68aa-63f5-405c-b178-9a4454556d6b"You can obtain the UUID of a store in the GUI as well via the context menu. If the API is enabled in the settings menu, you will find a new option in the context menu for stores and categories:
