Skip to main content

App Version API Documentation

Overview​

The App Version API provides endpoints for managing app version configurations for Android and iOS platforms. This includes minimum required versions, latest versions, update types (soft/force), and store URLs.

Public Endpoints​

Get Latest App Version​

Retrieves the most recent app version configuration. No authentication required.

Endpoint: GET /api/v1/app-version

Response:

{
  "android": {
    "latestVersion": "1.5.0",
    "minRequiredVersion": "1.3.0",
    "updateType": "soft",
    "storeUrl": "https://play.google.com/store/apps/details?id=com.zishes.app"
  },
  "ios": {
    "latestVersion": "1.5.0",
    "minRequiredVersion": "1.3.0",
    "updateType": "force",
    "storeUrl": "https://apps.apple.com/app/zishes/id123456789"
  },
  "updatedAt": "2025-10-03T10:30:00.000Z"
}

Status Codes:

  • 200 - Success
  • 404 - No version configuration found

Update Types:

  • soft - User can skip the update
  • force - User must update to continue using the app

Admin Endpoints​

All admin endpoints require admin authentication.

Get All App Versions​

Retrieves all app version configurations, sorted by most recent first.

Endpoint: GET /api/admin/app-version

Response:

{
  "data": [
    {
      "_id": "65f9a8b7c4d3e2f1a8b9c0d1",
      "androidLatestVersion": "1.5.0",
      "androidMinRequiredVersion": "1.3.0",
      "androidUpdateType": "soft",
      "androidStoreUrl": "https://play.google.com/store/apps/details?id=com.zishes.app",
      "iosLatestVersion": "1.5.0",
      "iosMinRequiredVersion": "1.3.0",
      "iosUpdateType": "force",
      "iosStoreUrl": "https://apps.apple.com/app/zishes/id123456789",
      "createdAt": "2025-10-03T10:00:00.000Z",
      "updatedAt": "2025-10-03T10:30:00.000Z"
    }
  ]
}

Get App Version by ID​

Retrieves a specific app version configuration.

Endpoint: GET /api/admin/app-version/:id

Response:

{
  "data": {
    "_id": "65f9a8b7c4d3e2f1a8b9c0d1",
    "androidLatestVersion": "1.5.0",
    "androidMinRequiredVersion": "1.3.0",
    "androidUpdateType": "soft",
    "androidStoreUrl": "https://play.google.com/store/apps/details?id=com.zishes.app",
    "iosLatestVersion": "1.5.0",
    "iosMinRequiredVersion": "1.3.0",
    "iosUpdateType": "force",
    "iosStoreUrl": "https://apps.apple.com/app/zishes/id123456789",
    "createdAt": "2025-10-03T10:00:00.000Z",
    "updatedAt": "2025-10-03T10:30:00.000Z"
  }
}

Status Codes:

  • 200 - Success
  • 404 - App version not found

Create App Version​

Creates a new app version configuration.

Endpoint: POST /api/admin/app-version

Request Body:

{
  "androidLatestVersion": "1.5.0",
  "androidMinRequiredVersion": "1.3.0",
  "androidUpdateType": "soft",
  "androidStoreUrl": "https://play.google.com/store/apps/details?id=com.zishes.app",
  "iosLatestVersion": "1.5.0",
  "iosMinRequiredVersion": "1.3.0",
  "iosUpdateType": "force",
  "iosStoreUrl": "https://apps.apple.com/app/zishes/id123456789"
}

Response:

{
  "data": {
    "_id": "65f9a8b7c4d3e2f1a8b9c0d1",
    "androidLatestVersion": "1.5.0",
    "androidMinRequiredVersion": "1.3.0",
    "androidUpdateType": "soft",
    "androidStoreUrl": "https://play.google.com/store/apps/details?id=com.zishes.app",
    "iosLatestVersion": "1.5.0",
    "iosMinRequiredVersion": "1.3.0",
    "iosUpdateType": "force",
    "iosStoreUrl": "https://apps.apple.com/app/zishes/id123456789",
    "createdAt": "2025-10-03T10:00:00.000Z",
    "updatedAt": "2025-10-03T10:00:00.000Z"
  },
  "message": "App version created successfully"
}

Status Codes:

  • 201 - Created successfully
  • 400 - Invalid update type (must be "soft" or "force")

Update App Version​

Updates an existing app version configuration. All fields are optional.

Endpoint: PUT /api/admin/app-version/:id

Request Body:

{
  "androidLatestVersion": "1.6.0",
  "androidUpdateType": "force",
  "iosLatestVersion": "1.6.0"
}

Response:

{
  "data": {
    "_id": "65f9a8b7c4d3e2f1a8b9c0d1",
    "androidLatestVersion": "1.6.0",
    "androidMinRequiredVersion": "1.3.0",
    "androidUpdateType": "force",
    "androidStoreUrl": "https://play.google.com/store/apps/details?id=com.zishes.app",
    "iosLatestVersion": "1.6.0",
    "iosMinRequiredVersion": "1.3.0",
    "iosUpdateType": "force",
    "iosStoreUrl": "https://apps.apple.com/app/zishes/id123456789",
    "createdAt": "2025-10-03T10:00:00.000Z",
    "updatedAt": "2025-10-03T11:00:00.000Z"
  },
  "message": "App version updated successfully"
}

Status Codes:

  • 200 - Updated successfully
  • 400 - Invalid update type
  • 404 - App version not found

Delete App Version​

Deletes an app version configuration.

Endpoint: DELETE /api/admin/app-version/:id

Response:

{
  "message": "App version deleted successfully",
  "data": {
    "_id": "65f9a8b7c4d3e2f1a8b9c0d1",
    "androidLatestVersion": "1.5.0",
    // ... other fields
  }
}

Status Codes:

  • 200 - Deleted successfully
  • 404 - App version not found

Field Descriptions​

FieldTypeDescription
androidLatestVersionStringLatest available Android version
androidMinRequiredVersionStringMinimum Android version required to use the app
androidUpdateTypeStringUpdate enforcement type: "soft" or "force"
androidStoreUrlStringGoogle Play Store URL
iosLatestVersionStringLatest available iOS version
iosMinRequiredVersionStringMinimum iOS version required to use the app
iosUpdateTypeStringUpdate enforcement type: "soft" or "force"
iosStoreUrlStringApple App Store URL

Usage Examples​

Mobile App Integration​

// Check if app needs update
const response = await fetch('https://api.zishes.com/api/v1/app-version');
const versionData = await response.json();

const currentVersion = "1.4.0";
const platform = Platform.OS; // "ios" or "android"

const minRequired = platform === "ios" 
  ? versionData.ios.minRequiredVersion 
  : versionData.android.minRequiredVersion;

const updateType = platform === "ios"
  ? versionData.ios.updateType
  : versionData.android.updateType;

const storeUrl = platform === "ios"
  ? versionData.ios.storeUrl
  : versionData.android.storeUrl;

// Compare versions
if (isVersionLessThan(currentVersion, minRequired)) {
  if (updateType === "force") {
    // Show mandatory update dialog
    showForceUpdateDialog(storeUrl);
  } else {
    // Show optional update dialog
    showSoftUpdateDialog(storeUrl);
  }
}

Admin Panel - Creating Version​

const createVersion = async () => {
  const response = await fetch('https://api.zishes.com/api/admin/app-version', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer <admin-token>'
    },
    body: JSON.stringify({
      androidLatestVersion: "1.5.0",
      androidMinRequiredVersion: "1.3.0",
      androidUpdateType: "soft",
      androidStoreUrl: "https://play.google.com/...",
      iosLatestVersion: "1.5.0",
      iosMinRequiredVersion: "1.3.0",
      iosUpdateType: "force",
      iosStoreUrl: "https://apps.apple.com/..."
    })
  });
  
  const result = await response.json();
  console.log(result.message); // "App version created successfully"
};

Best Practices​

  1. Version Updates:

    • Always create a new version document rather than updating existing ones
    • Keep historical versions for audit purposes

  2. Update Types:

    • Use force for critical security updates or breaking changes
    • Use soft for feature updates that maintain backward compatibility

  3. Version Strings:

    • Follow semantic versioning (e.g., "1.5.0")
    • Ensure minRequiredVersion ≤ latestVersion

  4. Testing:

    • Test version checks on staging before production release
    • Verify store URLs are correct and accessible

  5. Rollout Strategy:

    • Start with soft updates to monitor adoption
    • Switch to force only if necessary
    • Give users reasonable time to update before enforcing