Connect API
===========

The Connect API provides endpoints for managing social media network connections and integrations.

App Endpoints
-------------

Get Networks
~~~~~~~~~~~~

Retrieve user's connected social networks.

.. http:post:: /api/get/networks/

   **Response:**

   .. code-block:: json

      {
        "networks": [
          {
            "id": 123,
            "network": "instagram",
            "network_id": "user123",
            "network_url": "https://instagram.com/user123",
            "status": "accepted",
            "followers": 5000,
            "verified": true,
            "connected_at": "2024-01-01T00:00:00Z"
          },
          {
            "id": 124,
            "network": "facebook",
            "network_id": "page456",
            "network_url": "https://facebook.com/page456",
            "status": "pending",
            "followers": 2000,
            "verified": false,
            "connected_at": "2024-01-15T00:00:00Z"
          }
        ]
      }

Network Actions
~~~~~~~~~~~~~~~

Update Network Extra
^^^^^^^^^^^^^^^^^^^

Update additional information for a social network connection.

.. http:post:: /api/action/network-extra/update/

   **Request Body:**

   .. code-block:: text

      network_id=123
      extra_data[bio]=Updated bio information
      extra_data[website]=https://example.com
      extra_data[category]=fashion
      extra_data[engagement_rate]=3.5

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Network extra information updated successfully"
      }

Social Authentication
---------------------

Facebook Authentication
~~~~~~~~~~~~~~~~~~~~~~

Connect Facebook account.

.. http:post:: /api/auth/facebook/

   **Request Body:**

   .. code-block:: text

      access_token=facebook_access_token
      user_id=facebook_user_id

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Facebook account connected successfully",
        "network_id": 123
      }

Google Authentication
~~~~~~~~~~~~~~~~~~~~

Connect Google account.

.. http:post:: /api/auth/google/

   **Request Body:**

   .. code-block:: text

      access_token=google_access_token
      user_id=google_user_id

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Google account connected successfully",
        "network_id": 124
      }

Instagram Authentication
~~~~~~~~~~~~~~~~~~~~~~~

Connect Instagram account.

.. http:post:: /api/auth/instagram/

   **Request Body:**

   .. code-block:: text

      access_token=instagram_access_token
      user_id=instagram_user_id

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Instagram account connected successfully",
        "network_id": 125
      }

Twitter Authentication
~~~~~~~~~~~~~~~~~~~~~

Connect Twitter account.

.. http:post:: /api/auth/twitter/

   **Request Body:**

   .. code-block:: text

      access_token=twitter_access_token
      user_id=twitter_user_id

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Twitter account connected successfully",
        "network_id": 126
      }

Network Management
-----------------

Network Approval
~~~~~~~~~~~~~~~

Submit network for approval.

.. http:post:: /api/action/network/approval/

   **Request Body:**

   .. code-block:: json

      {
        "network_type": "instagram",
        "network_id": "user123",
        "network_url": "https://instagram.com/user123",
        "followers": 5000,
        "category": "fashion"
      }

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Network submitted for approval",
        "approval_id": 789
      }

Network Status
~~~~~~~~~~~~~

Get network connection status.

.. http:post:: /api/network/status/

   **Request Body:**

   .. code-block:: text

      network_id=123

   **Response:**

   .. code-block:: json

      {
        "status": "accepted",
        "verified": true,
        "followers": 5000,
        "engagement_rate": 3.5,
        "last_updated": "2024-08-01T10:00:00Z"
      }

Network Disconnect
~~~~~~~~~~~~~~~~~

Disconnect a social network.

.. http:post:: /api/network/disconnect/

   **Request Body:**

   .. code-block:: text

      network_id=123

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Network disconnected successfully"
      }

Social Pages
~~~~~~~~~~~

Get Social Pages
^^^^^^^^^^^^^^^

Retrieve user's social pages.

.. http:post:: /api/get/social-pages/

   **Response:**

   .. code-block:: json

      {
        "pages": [
          {
            "id": 456,
            "network": "facebook",
            "page_id": "page123",
            "page_name": "Fashion Blog",
            "page_url": "https://facebook.com/page123",
            "status": "accepted",
            "followers": 10000,
            "category": "fashion",
            "connected_at": "2024-01-01T00:00:00Z"
          }
        ]
      }

Add Social Page
^^^^^^^^^^^^^^

Add a new social page.

.. http:post:: /api/add/social-page/

   **Request Body:**

   .. code-block:: text

      network=facebook
      page_id=page456
      page_name=Beauty Blog
      page_url=https://facebook.com/page456
      followers=8000
      category=beauty

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Social page added successfully",
        "page_id": 457
      }

Social Walls
~~~~~~~~~~~

Get Social Walls
^^^^^^^^^^^^^^^

Retrieve user's social walls.

.. http:post:: /api/get/social-walls/

   **Response:**

   .. code-block:: json

      {
        "walls": [
          {
            "id": 789,
            "network": "instagram",
            "wall_id": "wall123",
            "wall_name": "Fashion Wall",
            "wall_url": "https://instagram.com/wall123",
            "status": "accepted",
            "followers": 5000,
            "category": "fashion",
            "connected_at": "2024-01-01T00:00:00Z"
          }
        ]
      }

Add Social Wall
^^^^^^^^^^^^^^

Add a new social wall.

.. http:post:: /api/add/social-wall/

   **Request Body:**

   .. code-block:: text

      network=instagram
      wall_id=wall456
      wall_name=Beauty Wall
      wall_url=https://instagram.com/wall456
      followers=3000
      category=beauty

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Social wall added successfully",
        "wall_id": 790
      }

Social Channels
~~~~~~~~~~~~~~

Get Social Channels
^^^^^^^^^^^^^^^^^^

Retrieve user's social channels.

.. http:post:: /api/get/social-channels/

   **Response:**

   .. code-block:: json

      {
        "channels": [
          {
            "id": 101,
            "network": "youtube",
            "channel_id": "channel123",
            "channel_name": "Fashion Channel",
            "channel_url": "https://youtube.com/channel123",
            "status": "accepted",
            "subscribers": 15000,
            "category": "fashion",
            "connected_at": "2024-01-01T00:00:00Z"
          }
        ]
      }

Add Social Channel
^^^^^^^^^^^^^^^^^

Add a new social channel.

.. http:post:: /api/add/social-channel/

   **Request Body:**

   .. code-block:: json

      {
        "network": "youtube",
        "channel_id": "channel456",
        "channel_name": "Beauty Channel",
        "channel_url": "https://youtube.com/channel456",
        "subscribers": 8000,
        "category": "beauty"
      }

   **Response:**

   .. code-block:: json

      {
        "status": "success",
        "message": "Social channel added successfully",
        "channel_id": 102
      }

Data Models
-----------

Social Network
~~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 123,
     "user_id": 456,
     "network": "instagram",
     "network_id": "user123",
     "network_url": "https://instagram.com/user123",
     "status": "accepted",
     "followers": 5000,
     "verified": true,
     "category": "fashion",
     "engagement_rate": 3.5,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "bio": "Fashion influencer",
       "website": "https://example.com",
       "verified_badge": true
     }
   }

Social Page
~~~~~~~~~~~

.. code-block:: json

   {
     "id": 456,
     "user_id": 456,
     "network": "facebook",
     "page_id": "page123",
     "page_name": "Fashion Blog",
     "page_url": "https://facebook.com/page123",
     "status": "accepted",
     "followers": 10000,
     "category": "fashion",
     "engagement_rate": 2.8,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "description": "Fashion and lifestyle blog",
       "category": "Fashion",
       "verification_status": "verified"
     }
   }

Social Wall
~~~~~~~~~~~

.. code-block:: json

   {
     "id": 789,
     "user_id": 456,
     "network": "instagram",
     "wall_id": "wall123",
     "wall_name": "Fashion Wall",
     "wall_url": "https://instagram.com/wall123",
     "status": "accepted",
     "followers": 5000,
     "category": "fashion",
     "engagement_rate": 4.2,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "description": "Curated fashion content",
       "posts_count": 150,
       "average_likes": 200
     }
   }

Social Channel
~~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 101,
     "user_id": 456,
     "network": "youtube",
     "channel_id": "channel123",
     "channel_name": "Fashion Channel",
     "channel_url": "https://youtube.com/channel123",
     "status": "accepted",
     "subscribers": 15000,
     "category": "fashion",
     "engagement_rate": 5.1,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "description": "Fashion and beauty videos",
       "videos_count": 50,
       "average_views": 5000
     }
   }

Network Status Values
--------------------

- **pending**: Network is submitted but not yet reviewed
- **accepted**: Network has been approved and is active
- **rejected**: Network has been rejected
- **suspended**: Network has been temporarily suspended
- **disconnected**: Network has been disconnected by user

Supported Networks
-----------------

- **Instagram**: Instagram personal accounts and business accounts
- **Facebook**: Facebook personal profiles and pages
- **Twitter**: Twitter accounts
- **YouTube**: YouTube channels
- **TikTok**: TikTok accounts
- **LinkedIn**: LinkedIn profiles and company pages
- **Pinterest**: Pinterest accounts and boards

Error Responses
--------------

Authentication Errors
~~~~~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "authentication_required",
     "message": "Authentication is required for this endpoint"
   }

.. code-block:: json

   {
     "error": "invalid_access_token",
     "message": "Invalid or expired access token"
   }

Network Errors
~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "network_already_connected",
     "message": "This network is already connected to your account"
   }

.. code-block:: json

   {
     "error": "network_not_found",
     "message": "Network not found"
   }

.. code-block:: json

   {
     "error": "network_verification_failed",
     "message": "Failed to verify network credentials"
   }

Validation Errors
~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Invalid network URL format",
     "field": "network_url"
   }

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Network type not supported",
     "field": "network"
   }

Permission Errors
~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "permission_denied",
     "message": "You don't have permission to access this network"
   }

.. code-block:: json

   {
     "error": "network_limit_reached",
     "message": "Maximum number of networks reached"
   }