At ftrack, we know that collaboration is vital to producing great output; individual effort is rarely enough. We extend this viewpoint to our own system: we recognise the importance of empowering developers, enabling them to extend and build on our tools to enhance the experience for the end user.

As such, we are proud to introduce the new API in ftrack 3.2. Written from scratch for the Python pipeline, the new solution provides greater flexibility and power whilst remaining approachable and intuitive. Whether you’re writing your very first script or you’re an experienced software architect, you’ll find our new API works the way you need it to.

Why a new API?

With the introduction of Workflows, ftrack is capable of supporting a greater diversity of industries. We’re enabling teams to closely align the system with their existing practices and naming conventions, resulting in a tool that feels more natural and intuitive. The old API was locked to specific workflows, making it impractical to support this new feature naturally.

We also wanted this new flexibility to extend to developers, so we set about redesigning the API to fully leverage the power in the system. And while we had the wrenches out, we figured why not go that extra mile and build in some of the features that we see developers having to continually implement in-house across different companies – features such as caching and support for custom pipeline extensions.

In essence, we decided to build the API that, as pipeline developers, we had always wanted from our production tracking and asset management systems. We think we succeeded, and we hope you agree.

Quick setup

Probably the first most important aspect of any API is making it easy to get started, so we made the decision to do a little extra and integrate with existing package repositories for our API clients.

To install the Python client for the API, all you need to do today is the familiar:

pip install ftrack-python-api

 

Approachable

An API needs to be approachable, so we built the ftrack 3.2 API to feel intuitive and familiar.

We bundle all the core functionality into one place – a session – with consistent methods for interacting with entities in the system:

import ftrack_api
    
session = ftrack_api.Session()

 

The core methods are straightforward:

Session.create – create a new entity, like a new version.
Session.query – fetch entities from the server using a powerful query language.
Session.delete – delete existing entities.
Session.commit – commit all changes in one efficient call.

In addition all entities in the API now act like simple Python dictionaries, with some additional helper methods where appropriate. If you know a little Python (or even if you don’t) getting up to speed should be a breeze:

>>> print user.keys()
['first_name', 'last_name', 'email', ...]
>>> print user['email']
'[email protected]'
>>> user['email'] = '[email protected]'

 

And of course, relationships between entities are reflected in a natural way as well:

new_timelog = session.create('Timelog', {...})
task['timelogs'].append(new_timelog)

 

Powerful query langauge

At the heart of the new API is a powerful query language that scales with requirements.

It’s easy to get started with…

session.query('Project where name is "My Project"').one()

…and flexible enough to express your needs in optimised queries:

tasks = session.query(
    'select name, parent.name from Task '
    'where project.full_name is "My Project" '
    'and status.type.name is "DONE" '
    'and not timelogs any ()'
).all()

 

The above fetches all tasks for “My Project” that are done but have no timelogs. It also pre-fetches related information about the tasks parent – all in one efficient query.

Built-in caching

In this new API we chose to tackle some of the common issues that developers face using an API in larger productions.

Our first significant contribution is a built-in caching system to optimise retrieval of frequently used data within a session. The cache is present by default so everyone benefits from the default setup, but if you want to take it further rest assured that we have you covered. For example, configuring a per-site, selective persistent cache is just a few lines of code away.

We will continue to evolve the caching system over time, building in smart cache invalidation and cached queries with the possibility to even support limited offline usage of the API.

Extendable

There comes a point with most APIs where you need more than just the basics. We didn’t want reaching that point to incur a large cost or necessitate precious development time wrapping our API to provide additional functionality.

We decided to embrace the need of deeper functionality by building the higher level API out of exposed lower level building blocks that external developers can reuse.

As a result there exists in the new API powerful hooks for customising entity classes and methods to seamlessly integrate your specific pipeline methodologies into the core.

Backwards compatibility

With so many powerful new features and the necessary support for more flexible workflows, we chose early on to not limit the new API design by necessitating backwards compatibility. However, we also didn’t want to force teams using the existing API to make a costly all-or-nothing switchover. As such, we have made the new API capable of coexisting in the same process as the old API:

import ftrack
import ftrack_api

 

In addition, the old API will continue to be supported for some time, but do note that it will not support the new Workflows and will not have new features back ported to it.

Take it out for a spin

There is still more to do and we will be continually working on the API to reach our end goal: covering every aspect of the system.

However, we think the new API is now ready to take out for a spin and we encourage you to do as soon as it is officially released. Read more at the dedicated documentation site and provide feedback via support email or our forums.

Leave a Reply