BeatConnect API

Getting Started

The BeatConnect API provides programmatic access to beats, users, genres, and transactions on our platform. You can use our API to create applications that integrate with BeatConnect, build custom experiences, or analyze data from the marketplace.

Authentication

To use the BeatConnect API, you'll need an API key. You can obtain one by registering in the Developer Portal.

All API requests must include your API key in the Authorization header:

GET /v1/beats HTTP/1.1
Host: api.beatconnectafrica.com
Authorization: Bearer YOUR_API_KEY
Accept: application/json

Rate Limiting

The API is rate limited to protect our services from abuse. Standard API keys allow:

• 1,000 requests per day
• 100 requests per hour
• 10 requests per minute

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1635962440

If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating how long to wait before making another request.

Interactive API Explorer

Try API calls directly from your browser using the interactive Swagger UI. All endpoints are auto-documented from the source code.

API Endpoints

{
  "status": "success",
  "data": {
    "beats": [
      {
        "id": 1234,
        "title": "Summer Vibes",
        "user_id": 5678,
        "producer_name": "DJ Maphorisa",
        "genre": {
          "id": 1,
          "name": "Amapiano"
        },
        "price": 49.99,
        "duration": 180,
        "bpm": 115,
        "key": "C minor",
        "audio_url": "https://api.beatconnectafrica.com/audio/1234.mp3",
        "cover_image": "https://api.beatconnectafrica.com/images/1234.jpg",
        "created_at": "2023-04-15T12:34:56Z",
        "play_count": 3240,
        "download_count": 129
      },
      // More beats...
    ],
    "pagination": {
      "total": 253,
      "per_page": 20,
      "current_page": 1,
      "last_page": 13,
      "next_page_url": "https://api.beatconnectafrica.com/v1/beats?page=2",
      "prev_page_url": null
    }
  }
}

curl -X GET "https://api.beatconnectafrica.com/v1/beats?genre=1&sort=popular" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

curl -X GET "https://api.beatconnectafrica.com/v1/beats/1234" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

curl -X GET "https://api.beatconnectafrica.com/v1/beats/1234/similar?limit=3" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

curl -X GET "https://api.beatconnectafrica.com/v1/users/5678" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

curl -X GET "https://api.beatconnectafrica.com/v1/genres" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

curl -X GET "https://api.beatconnectafrica.com/v1/search?q=amapiano&type=beats" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

curl -X GET "https://api.beatconnectafrica.com/v1/orders?status=completed" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: application/json"

Error Handling

When an error occurs, the API will return an appropriate HTTP status code and a JSON response with details about the error.

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": "The 'genre' parameter must be a valid integer"
  }
}

Common Error Codes

Webhooks

Webhooks allow you to receive real-time notifications when certain events occur on the BeatConnect platform. This is useful for keeping your application in sync with changes without polling the API.

Setting Up Webhooks

To set up a webhook, go to the Developer Portal and provide the URL where you want to receive webhook events. You can also specify which events you want to subscribe to.

Webhook Events

Webhook Payload

Webhook payloads include a signature in the X-Webhook-Signature header that you can use to verify the webhook came from BeatConnect.

{
  "id": "evt_123456789",
  "created": 1635962400,
  "type": "beat.purchased",
  "data": {
    "beat_id": 1234,
    "title": "Summer Vibes",
    "producer_id": 5678,
    "producer_name": "DJ Maphorisa",
    "license_type": "Premium",
    "amount": 49.99,
    "currency": "USD",
    "purchaser_id": 9012
  }
}

Verifying Webhooks

To verify that a webhook came from BeatConnect, you should compute an HMAC with the SHA-256 hash function. The HMAC should be computed using your webhook secret as the key and the request body as the message.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computedSignature = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

// Express.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const secret = 'your_webhook_secret';

  if (verifyWebhookSignature(payload, signature, secret)) {
    // Webhook is verified, process the event
    const event = req.body;

    res.status(200).send('Webhook received');
  } else {
    // Invalid signature
    res.status(401).send('Invalid signature');
  }
});

import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_webhook_signature(payload, signature, secret):
    computed_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed_signature, signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.data.decode('utf-8')
    signature = request.headers.get('X-Webhook-Signature')
    secret = 'your_webhook_secret'

    if verify_webhook_signature(payload, signature, secret):
        # Webhook is verified, process the event
        event = json.loads(payload)
        print(f"Received event: {event['type']}")

        return jsonify({'status': 'success'}), 200
    else:
        # Invalid signature
        return jsonify({'status': 'error', 'message': 'Invalid signature'}), 401

if __name__ == '__main__':
    app.run(debug=True)