API Documentation Guide

Welcome to the MyGigsters Super API Documentation. This guide will help you understand how to navigate the documentation and test the APIs effectively.

Understanding the Documentation Structure

Navigation

Use the sidebar on the left to navigate through different sections of the API documentation:

  • Getting Started: Overview of the platform and core features
  • API Guide: This comprehensive guide (you're reading it now!)
  • API Keys: Learn how to create and manage API keys for authentication
  • Authentication: Learn how to authenticate your requests
  • Employees: Endpoints for managing employee data
  • Validation: Endpoints for validating super contributions
  • Submission: Endpoints for submitting super contributions

API Endpoint Pages

Each API endpoint page contains the following sections:

  1. Endpoint Summary: A brief description of what the endpoint does
  2. HTTP Method & Path: The request method (GET, POST, etc.) and the API path
  3. Request Parameters: Path and query parameters required or optional for the request
  4. Request Body: The JSON structure for POST/PUT requests
  5. Responses: All possible response codes with their schemas
  6. Sample Request: A ready-to-use cURL command you can copy and test
  7. Sample Response: Example JSON responses for successful requests

Authentication Flow

Authentication

All API requests (except authentication endpoints) require Basic Authentication using your API Key credentials. For detailed authentication instructions including how to create API keys, encode credentials, and send authorization headers, please refer to the Authentication guide.

You can create and manage your API keys in the API Keys section.

How to Test the APIs

Method 1: Using cURL (Command Line)

Each endpoint page provides a ready-to-use cURL command. Simply:

  1. Copy the cURL command from the "Sample Request" section
  2. Replace placeholder values (like apiUsername:apiPassword) with your actual API credentials
  3. Replace any example IDs or parameters with real values
  4. Paste and run the command in your terminal
# Example: Get all employees
curl 'https://super.mygigsters.com.au/v1/employees' \
  -u 'apiUsername:apiPassword'

Method 2: Using Postman

  1. Open Postman and create a new request
  2. Set the HTTP method (GET, POST, etc.)
  3. Enter the full URL: https://super.mygigsters.com.au/v1/endpoint
  4. Go to the "Authorization" tab
  5. Select "Basic Auth" and enter your apiUsername as username and apiPassword as password
  6. For POST/PUT requests, go to "Body" tab, select "raw" and "JSON", then paste the request body from the documentation
  7. Click "Send" to make the request

Method 3: Using JavaScript (Fetch API)

// Example: Get all employees
const username = 'apiUsername';
const password = 'apiPassword';
const credentials = btoa(`${username}:${password}`);

fetch('https://super.mygigsters.com.au/v1/employees', {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Method 4: Using Python (requests library)

import requests
from requests.auth import HTTPBasicAuth

# Example: Get all employees
url = 'https://super.mygigsters.com.au/v1/employees'
username = 'apiUsername'
password = 'apiPassword'

response = requests.get(
    url,
    auth=HTTPBasicAuth(username, password)
)

print(response.json())

Typical API Workflow

Complete Integration Flow

  1. Create API Keys: Navigate to API Keys and create a new key. Save the apiUsername and apiPassword securely.
  2. Register Employees: Use the Employees endpoints to register gig workers with their details.
  3. Validate Contributions: Before submitting, use the Validation endpoints to ensure your contribution data is correct.
  4. Submit Contributions: Once validated, use the Submission endpoints to submit super contributions for your employees.

Important Notes

Security Best Practices

  • Never commit API keys to version control
  • Store credentials in environment variables
  • Rotate API keys regularly
  • Delete unused API keys immediately
  • Use HTTPS for all API requests (never HTTP)

Error Handling

  • Always check response status codes
  • Handle 4xx errors (client errors) appropriately
  • Implement retry logic for 5xx errors (server errors)
  • Log errors for debugging purposes
  • Review error messages in response bodies for details

Rate Limiting

Be mindful of API rate limits. If you encounter rate limit errors:

  • Implement exponential backoff in your retry logic
  • Cache responses when appropriate
  • Batch requests when possible
  • Monitor your API usage

Getting Help

If you encounter any issues or have questions:

  • Review the endpoint documentation carefully
  • Check the sample requests and responses
  • Verify your authentication credentials
  • Ensure request body formats match the schema
  • Contact support with specific error messages and request details

Ready to Get Started?

Now that you understand how to use the documentation, head over to the API Keys section to create your first API key and start making requests!

Go to API Keys →