Basic API Documentation

What is the Basic API?

The Basic API uses standard authentication methods that are simple to implement and understand. This is the original API authentication method, maintained for backwards compatibility and ease of use.

When to Use Basic API

• Quick prototyping - Get up and running in minutes
• Simple integrations - Straightforward authentication without token management
• Legacy support - Existing integrations that rely on this method
• Internal tools - Simple scripts and internal applications

Method 1: API Key in Query Parameters

Pass your API key directly in the URL as a query parameter:

GET https://api.mobile.digital/endpoint?api_key=YOUR_API_KEY

Method 2: Custom Header

Include your API key in a custom header:

GET https://api.mobile.digital/endpoint
X-API-Key: YOUR_API_KEY

Method 3: HTTP Basic Authentication

Use standard HTTP Basic Auth with your username and password:

GET https://api.mobile.digital/endpoint
Authorization: Basic base64(username:password)

Getting Your Credentials

Your API credentials are available from:

• Your account dashboard
• Your system administrator
• Initial account setup email

1. Step 1: Obtain Your API Key

   Contact your administrator or check your account dashboard to obtain your API key.

2. Step 2: Test the API Explorer
   1. Visit the Basic API Explorer
   2. Click the Authorize button
   3. Enter your API credentials
   4. Try out the available endpoints
3. Step 3: Make Your First Call

   Test with a simple API call using cURL:

   curl -X GET 'https://api.mobile.digital/test?api_key=YOUR_API_KEY'

   Success! If you receive a 200 OK response, your API key is working correctly.

Python Example - Query Parameter

import requests

api_key = "your_api_key_here"
base_url = "https://api.mobile.digital"

# Example: Send SMS
endpoint = f"{base_url}/sendSMS"
params = {
    "api_key": api_key,
    "recipient": "+61400000000",
    "message": "Hello from Python!"
}

response = requests.get(endpoint, params=params)
print(response.json())

Python Example - Header Authentication

import requests

api_key = "your_api_key_here"
base_url = "https://api.mobile.digital"

# Example: Send SMS with header auth
endpoint = f"{base_url}/sendSMS"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}
data = {
    "recipient": "+61400000000",
    "message": "Hello from Python with headers!"
}

response = requests.post(endpoint, headers=headers, json=data)
print(response.json())

cURL Example - Query Parameter

curl -X POST 'https://api.mobile.digital/sendSMS?api_key=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "+61400000000",
    "message": "Hello from cURL!"
  }'

cURL Example - Header Authentication

curl -X POST 'https://api.mobile.digital/sendSMS' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "+61400000000",
    "message": "Hello from cURL with headers!"
  }'

PHP Example

<?php
$api_key = "your_api_key_here";
$base_url = "https://api.mobile.digital";

// Example: Send SMS
$endpoint = "$base_url/sendSMS";
$data = [
    "recipient" => "+61400000000",
    "message" => "Hello from PHP!"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint . "?api_key=" . urlencode($api_key));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Response ($http_code): $response\n";
?>

Node.js Example

const axios = require('axios');

const apiKey = 'your_api_key_here';
const baseUrl = 'https://api.mobile.digital';

// Example: Send SMS with header auth
async function sendSMS() {
    try {
        const response = await axios.post(
            `${baseUrl}/sendSMS`,
            {
                recipient: '+61400000000',
                message: 'Hello from Node.js!'
            },
            {
                headers: {
                    'X-API-Key': apiKey,
                    'Content-Type': 'application/json'
                }
            }
        );

        console.log('Response:', response.data);
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}

sendSMS();

JavaScript (Fetch API)

const apiKey = 'your_api_key_here';
const baseUrl = 'https://api.mobile.digital';

// Example: Send SMS
fetch(`${baseUrl}/sendSMS`, {
    method: 'POST',
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        recipient: '+61400000000',
        message: 'Hello from JavaScript!'
    })
})
.then(response => response.json())
.then(data => console.log('Response:', data))
.catch(error => console.error('Error:', error));

Why Migrate to OAuth2?

While the Basic API is simple and functional, OAuth2 offers several advantages:

Migration Steps

1. Get OAuth2 Credentials
   • Request client_id and client_secret from your administrator
2. Review Documentation
   • Read the OAuth2 API Documentation
   • Understand the Client Credentials flow
3. Update Your Code
   • Replace API key with OAuth2 token acquisition
   • Add token caching and refresh logic
4. Test in Sandbox
   • Use the OAuth2 API Explorer
   • Validate with test credentials first
5. Deploy Gradually
   • Run both methods in parallel during transition
   • Monitor and validate OAuth2 integration
   • Retire Basic API credentials once stable

Side-by-Side Comparison

Basic API:

curl -X POST 'https://api.mobile.digital/sendSMS?api_key=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "+61400000000", "message": "Hello!"}'

OAuth2 API:

# Step 1: Get token (cache this for 1 hour)
TOKEN=$(curl -X POST 'https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/oauth2/token' \
  -H 'Authorization: Basic $(echo -n "client_id:client_secret" | base64)' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=read write' \
  | jq -r '.access_token')

# Step 2: Use token in API call
curl -X POST 'https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/sendSMS' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "+61400000000", "message": "Hello!"}'

Security

• Always use HTTPS, never HTTP
• Store API keys in environment variables, not in code
• Use header authentication instead of query parameters when possible
• Rotate API keys periodically
• Never commit API keys to version control
• Use separate keys for development/staging/production

Error Handling

• Check HTTP status codes (200 = success, 401 = unauthorized, etc.)
• Implement retry logic with exponential backoff
• Log errors with context for debugging
• Handle network timeouts gracefully

Performance

• Reuse HTTP connections when making multiple requests
• Implement request rate limiting to avoid throttling
• Cache API responses when appropriate
• Use compression (Accept-Encoding: gzip)