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

Introduction

Hey there, fellow developer! Ready to dive into the world of Freelancer API integration? You're in for a treat. We'll be using the freelancersdk package to make our lives easier. This guide assumes you're already familiar with Python and API basics, so we'll keep things snappy and focus on the good stuff.

Prerequisites

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

• A Python environment set up (I know you've got this!)
• The freelancersdk package installed (pip install freelancersdk)
• API credentials from Freelancer (grab these from your account settings)

Setting up the API Client

Let's get the ball rolling:

from freelancersdk.session import Session
from freelancersdk.resources.projects import projects

oauth_token = 'your_oauth_token_here'
session = Session(oauth_token=oauth_token)

Easy peasy, right? We've just initialized our FreelancerApi object.

Basic API Operations

Now for the fun part - let's authenticate and handle some responses:

try:
    projects = projects.search_projects(session, query='python')
    print(projects)
except Exception as e:
    print('Error occurred: {}'.format(e))

Pro tip: Always wrap your API calls in try-except blocks. Trust me, your future self will thank you.

Key API Endpoints and Functionalities

Projects

Searching for projects is just the beginning. Let's post one:

from freelancersdk.resources.projects.projects import create_project

project_data = {
    'title': 'Need a Python wizard',
    'description': 'Looking for a Python expert to build an API integration',
    'budget': {'minimum': 500, 'maximum': 1000},
    'currency': {'id': 1},  # USD
}

try:
    project = create_project(session, **project_data)
    print("Project created successfully!")
except Exception as e:
    print('Error creating project: {}'.format(e))

Bids

Placing a bid is just as straightforward:

from freelancersdk.resources.projects.projects import place_project_bid

bid_data = {
    'project_id': 123456,
    'bidder_id': 7890,
    'amount': 750,
    'period': 7,
    'description': 'I'm your Python wizard! Let's make magic happen.',
}

try:
    bid = place_project_bid(session, **bid_data)
    print("Bid placed successfully!")
except Exception as e:
    print('Error placing bid: {}'.format(e))

Users

Getting user details is a breeze:

from freelancersdk.resources.users import users

try:
    user = users.get_self(session)
    print(f"Hello, {user['username']}!")
except Exception as e:
    print('Error getting user details: {}'.format(e))

Advanced Usage

Want to handle pagination like a pro? Check this out:

from freelancersdk.resources.projects.projects import search_projects

offset = 0
limit = 10
total_count = 0

while True:
    try:
        result = search_projects(session, query='python', offset=offset, limit=limit)
        projects = result['projects']
        total_count += len(projects)
        
        # Process projects here
        
        if len(projects) < limit:
            break
        
        offset += limit
    except Exception as e:
        print('Error occurred: {}'.format(e))
        break

print(f"Total projects processed: {total_count}")

Error Handling and Best Practices

Remember, the API has rate limits. Be a good citizen and implement exponential backoff:

import time
from requests.exceptions import RequestException

def api_call_with_retry(func, max_retries=3, base_delay=1):
    retries = 0
    while retries < max_retries:
        try:
            return func()
        except RequestException as e:
            wait = base_delay * (2 ** retries)
            print(f"Request failed: {e}. Retrying in {wait} seconds...")
            time.sleep(wait)
            retries += 1
    
    raise Exception("Max retries reached. API call failed.")

Testing and Debugging

Always use the sandbox environment for testing:

sandbox_oauth_token = 'your_sandbox_oauth_token_here'
sandbox_session = Session(oauth_token=sandbox_oauth_token, url='https://www.freelancer-sandbox.com')

And don't forget to log everything. Future you will be grateful:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

try:
    project = create_project(session, **project_data)
    logger.info(f"Project created successfully! ID: {project['id']}")
except Exception as e:
    logger.error(f"Error creating project: {e}")

Conclusion

And there you have it! You're now equipped to build a robust Freelancer API integration. Remember, the official documentation is your best friend for diving deeper into specific endpoints and features.

Now go forth and code something awesome! 🚀