Getting Started with API

This article is an overview of our API with a focus on our Python API Client, but we also support other clients.

• 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 recognize 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 and 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)

To see the list of available schemas and their attributes on your ftrack workspace, click on "API reference" under the help menu from your user menu in the top right corner.

Powerful query language

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 optimized 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 optimize 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 to reach 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 for 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 customizing entity classes and methods to seamlessly integrate your specific pipeline methodologies into the core.