This article is an overview of our API with a focus on our Python API Client, but we also support other clients. For a more in-depth discussion about our underlaying server API, see API overview.

An overview introduction to our Python API and key concepts.

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.

Written from scratch for the Python pipeline, our API 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 API works the way you need it to. 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 and more.

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

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 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']
'old@example.com'
>>> user['email'] = 'new@example.com'

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 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 time logs. It also pre-fetches related information about the tasks parent – all in one efficient query.

Built-in caching

In our 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.

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.

More

Learn more about  our API clients
Check out our coding examples
Learn more about Key concepts
Visit our forum for all API related things

Did this answer your question?