Step by Step Guide to Building a Process Street API Integration in PHP

Introduction

Hey there, fellow code wranglers! Ready to supercharge your workflow management with Process Street's API? You're in the right place. We're going to walk through building a slick PHP integration that'll have you automating processes faster than you can say "efficiency boost". Let's dive in!

Prerequisites

Before we start cooking, let's make sure we've got all our ingredients:

• A PHP environment (you've got this, right?)
• Your Process Street API key (if you don't have one, go grab it from your account settings)
• cURL library (because who doesn't love a good cURL?)

Setting up the API Client

First things first, let's create a base API class. This'll be our Swiss Army knife for all Process Street operations.

class ProcessStreetAPI {
    private $apiKey;
    private $baseUrl = 'https://api.process.st/api/v1';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    // We'll add more methods here soon!
}

Core API Operations

Now, let's add some meat to our API class. We'll focus on three key operations:

Fetching Workflows

public function getWorkflows() {
    return $this->makeRequest('GET', '/workflows');
}

Creating a Workflow Run

public function createWorkflowRun($workflowId, $data) {
    return $this->makeRequest('POST', "/workflows/{$workflowId}/runs", $data);
}

Updating Task Status

public function updateTaskStatus($runId, $taskId, $status) {
    $data = ['status' => $status];
    return $this->makeRequest('PUT', "/runs/{$runId}/tasks/{$taskId}", $data);
}

Error Handling and Rate Limiting

Let's not forget to play nice with the API. We'll wrap our requests in try-catch blocks and respect those rate limits:

private function makeRequest($method, $endpoint, $data = null) {
    $curl = curl_init($this->baseUrl . $endpoint);
    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($curl, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $this->apiKey,
        'Content-Type: application/json'
    ]);

    if ($data) {
        curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
    }

    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

    try {
        $response = curl_exec($curl);
        if (curl_getinfo($curl, CURLINFO_HTTP_CODE) === 429) {
            // Handle rate limiting
            sleep(60); // Wait for a minute and try again
            return $this->makeRequest($method, $endpoint, $data);
        }
        return json_decode($response, true);
    } catch (Exception $e) {
        // Handle the error
        return ['error' => $e->getMessage()];
    } finally {
        curl_close($curl);
    }
}

Example Integration: Automating Workflow Creation

Let's put it all together with a real-world example. We'll create a function that starts a new workflow run when a user signs up:

function onUserSignup($userId) {
    $api = new ProcessStreetAPI('your-api-key-here');
    $workflowId = 'your-workflow-id';
    
    $data = [
        'name' => "New User Onboarding - User {$userId}",
        'variables' => [
            'userId' => $userId,
            'signupDate' => date('Y-m-d H:i:s')
        ]
    ];

    $result = $api->createWorkflowRun($workflowId, $data);

    if (isset($result['error'])) {
        // Handle the error
        error_log("Failed to create workflow run: " . $result['error']);
    } else {
        // Success! Maybe update your user record with the run ID?
        updateUserRecord($userId, $result['id']);
    }
}

Testing and Debugging

Don't forget to test your integration thoroughly. Here's a quick unit test to get you started:

function testWorkflowCreation() {
    $api = new ProcessStreetAPI('your-test-api-key');
    $result = $api->createWorkflowRun('test-workflow-id', ['name' => 'Test Run']);
    assert(isset($result['id']), 'Workflow run creation failed');
}

Best Practices

1. Cache API responses where possible to reduce API calls.
2. Store your API key securely (use environment variables, not hard-coded strings).
3. Implement proper error logging and monitoring.

Conclusion

And there you have it! You've just built a robust Process Street API integration in PHP. With this foundation, you can automate workflows, track tasks, and supercharge your processes. Remember, the API is your oyster - there's so much more you can do with it.

Happy coding, and may your workflows be ever efficient!

Code Repository

For the full example code and more advanced usage, check out our GitHub repository.