Step by Step Guide to Building a Teamwork API Integration in Python

Aug 15, 2024 • 6 minute read

Introduction

Hey there, fellow developer! Ready to supercharge your project management with some Python magic? Today, we're diving into the world of Teamwork API integration. Whether you're looking to automate your workflow or build a custom tool, this guide will get you up and running in no time.

Prerequisites

Before we jump in, make sure you've got:

A Python environment (3.6+ recommended)
The requests library installed (pip install requests)
A Teamwork API key (grab one from your Teamwork account settings)

Got all that? Great! Let's get coding.

Setting up the API Connection

First things first, let's set up our connection:

import requests

BASE_URL = "https://your-domain.teamwork.com/api/v3"
API_KEY = "your_api_key_here"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

Basic API Requests

Now, let's make some noise with basic GET and POST requests:

# GET request
def get_projects():
    response = requests.get(f"{BASE_URL}/projects.json", headers=headers)
    return response.json()

# POST request
def create_task(project_id, task_name):
    data = {"todo-item": {"content": task_name}}
    response = requests.post(f"{BASE_URL}/projects/{project_id}/tasks.json", headers=headers, json=data)
    return response.json()

Pro tip: Always check the response status and handle errors gracefully!

Implementing Key Teamwork Features

Let's tackle some core Teamwork features:

Projects

def list_projects():
    projects = get_projects()
    for project in projects['projects']:
        print(f"Project: {project['name']}")

def create_project(name):
    data = {"project": {"name": name}}
    response = requests.post(f"{BASE_URL}/projects.json", headers=headers, json=data)
    return response.json()

Tasks

def fetch_tasks(project_id):
    response = requests.get(f"{BASE_URL}/projects/{project_id}/tasks.json", headers=headers)
    return response.json()

# We've already covered creating tasks above!

Time Tracking

def log_time(task_id, hours):
    data = {"time-entry": {"hours": hours}}
    response = requests.post(f"{BASE_URL}/tasks/{task_id}/time_entries.json", headers=headers, json=data)
    return response.json()

def get_time_entries(project_id):
    response = requests.get(f"{BASE_URL}/projects/{project_id}/time_entries.json", headers=headers)
    return response.json()

Data Processing and Manipulation

When working with API responses, you'll often need to parse and structure data:

import json

def parse_projects(response):
    projects = response['projects']
    return [{'id': p['id'], 'name': p['name']} for p in projects]

def prepare_task_data(task_name, description, due_date):
    return {
        "todo-item": {
            "content": task_name,
            "description": description,
            "due-date": due_date
        }
    }

Building a Simple CLI Tool

Let's wrap this all up in a neat CLI package:

import argparse

def main():
    parser = argparse.ArgumentParser(description="Teamwork API CLI")
    parser.add_argument('action', choices=['list_projects', 'create_task', 'log_time'])
    parser.add_argument('--project_id', help="Project ID for task creation")
    parser.add_argument('--task_name', help="Name of the task to create")
    parser.add_argument('--task_id', help="Task ID for time logging")
    parser.add_argument('--hours', type=float, help="Hours to log")

    args = parser.parse_args()

    if args.action == 'list_projects':
        list_projects()
    elif args.action == 'create_task':
        create_task(args.project_id, args.task_name)
    elif args.action == 'log_time':
        log_time(args.task_id, args.hours)

if __name__ == "__main__":
    main()

Best Practices and Optimization

Remember to:

Respect rate limits (Teamwork has a 150 requests per minute limit)
Implement caching for frequently accessed data
Log errors and handle exceptions gracefully

Testing the Integration

Don't forget to test! Here's a quick example using unittest:

import unittest

class TestTeamworkAPI(unittest.TestCase):
    def test_get_projects(self):
        projects = get_projects()
        self.assertIsNotNone(projects)
        self.assertIn('projects', projects)

    # Add more tests for other functions

Conclusion

And there you have it! You've just built a solid foundation for your Teamwork API integration. From here, you can expand on this base, add more features, or even build a full-fledged Teamwork companion app. The sky's the limit!

Remember, the best way to learn is by doing. So go ahead, tweak this code, break things, and build something awesome. You've got this!

Resources

Happy coding, and may your projects always be on time and under budget!