diff --git a/src/pages/docs/api/binary-apps.md b/src/pages/docs/api/binary-apps.md index 2e67d58..9c6fcba 100644 --- a/src/pages/docs/api/binary-apps.md +++ b/src/pages/docs/api/binary-apps.md @@ -65,19 +65,33 @@ curl -X GET "https://api.test.io/customer/v2/binary_apps/upload_url" \ **Response:** `200 OK` +**Response Attributes:** + +- `binary_app_id` (number, required) - The ID of the created binary app (use this in the finalization step) +- `url` (string, required) - S3 presigned POST URL +- `fields` (object, required) - Form fields required for the S3 POST request + - `key` (string, required) - S3 object key pattern. **IMPORTANT:** `${filename}` is a placeholder - replace it with your actual filename when uploading to S3. For example, if uploading `MyApp-v1.2.3.apk`, the key should be `uploads/binary_app/package/123/MyApp-v1.2.3.apk` + - `success_action_status` (string, required) - HTTP status code S3 will return on success + - `policy` (string, required) - Base64-encoded upload policy + - `x-amz-credential` (string, required) - AWS credential for the upload + - `x-amz-algorithm` (string, required) - AWS signature algorithm + - `x-amz-date` (string, required) - Request timestamp + - `x-amz-signature` (string, required) - Request signature + {% code language="json" showLineNumbers=true %} ```json { "binary_app_id": 123, - "url": "https://upload.test.io/direct", + "url": "https://my-bucket.s3.eu-west-1.amazonaws.com", "fields": { - "key": "uploads/binary_app/123/${filename}", + "key": "uploads/binary_app/package/123/${filename}", "success_action_status": "201", - "policy": "", - "algorithm": "", - "date": "20251104T154715Z", - "signature": "" + "policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0xMS0wNFQxNjo0NzoxNVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJteS1idWNrZXQifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsInVwbG9hZHMvYmluYXJ5X2FwcC9wYWNrYWdlLzEyMy8iXSx7InN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyI6IjIwMSJ9LFsiY29udGVudC1sZW5ndGgtcmFuZ2UiLDEsMTA3Mzc0MTgyNF1dfQ==", + "x-amz-credential": "AKIAEXAMPLE/20251104/eu-west-1/s3/aws4_request", + "x-amz-algorithm": "AWS4-HMAC-SHA256", + "x-amz-date": "20251104T154715Z", + "x-amz-signature": "abc123def456..." } } ``` @@ -86,30 +100,25 @@ curl -X GET "https://api.test.io/customer/v2/binary_apps/upload_url" \ ## Finalize binary app upload -Finalize a direct upload by validating metadata, verifying the file exists in storage, and generating a public download URL. +Finalizes a direct storage upload by validating metadata, verifying the file exists in storage, and generating a public download URL. + +**Important:** After uploading to S3, you have to call this endpoint with the file metadata to complete the process. **Endpoint:** `PUT /binary_apps/{id}` **Parameters:** -- `id` (number, required) - Binary app ID from GET /binary_apps/upload_url +- `id` (number, required) - Binary app ID from `GET /binary_apps/upload_url` -**Request Body:** - -{% code language="json" showLineNumbers=true %} +**Request Body Attributes:** -```json -{ - "filename": "MyApp-v1.2.3.apk", - "file_size": 524288000, - "content_type": "application/vnd.android.package-archive", - "bundle_identifier": "com.example.myapp", - "bundle_version": "1.2.3", - "url": "https://files.test.io/uploads/binary_app/13/MyApp-v1.2.3.apk" -} -``` - -{% /code %} +- `filename` (string, required) - The name of the file uploaded to S3. Must match the filename used in the S3 upload. Used to construct the S3 key for verification. +- `file_size` (number, required) - Size of the uploaded file in bytes. Must not exceed 1GB (1073741824 bytes). This should match the actual file size uploaded to S3. +- `content_type` (string, required) - MIME type of the uploaded file. Common values: + - `application/vnd.android.package-archive` - APK (Android) + - `application/octet-stream` - IPA (iOS) +- `bundle_identifier` (string, optional) - The unique bundle/package identifier for the app (e.g., `com.example.myapp` for Android or iOS). +- `bundle_version` (string, optional) - The version string of the app bundle (e.g., `1.2.3` or `4.2.11.5100000`). **Example Request:** @@ -124,8 +133,7 @@ curl -X PUT "https://api.test.io/customer/v2/binary_apps/123" \ "file_size": 524288000, "content_type": "application/vnd.android.package-archive", "bundle_identifier": "com.example.myapp", - "bundle_version": "1.2.3", - "url": "https://testcloud-staging-webapp.s3.eu-west-1.amazonaws.com/uploads/binary_app/package/13/MyApp-v1.2.3.apk" + "bundle_version": "1.2.3" }' ``` @@ -133,6 +141,17 @@ curl -X PUT "https://api.test.io/customer/v2/binary_apps/123" \ **Response:** `200 OK` +**Response Attributes:** + +- `binary_app` (object) + - `id` (number) - Binary app ID + - `filename` (string) - The uploaded file name + - `file_size` (number) - File size in bytes + - `content_type` (string) - File MIME type + - `bundle_identifier` (string, nullable) - App bundle identifier + - `bundle_version` (string, nullable) - App version + - `status` (string) - Binary app status + {% code language="json" showLineNumbers=true %} ```json @@ -141,22 +160,49 @@ curl -X PUT "https://api.test.io/customer/v2/binary_apps/123" \ "id": 123, "filename": "MyApp-v1.2.3.apk", "file_size": 524288000, - "url": "https://files.test.io/uploads/binary_app/123/MyApp-v1.2.3.apk" + "content_type": "application/vnd.android.package-archive", + "bundle_identifier": "com.example.myapp", + "bundle_version": "1.2.3", + "status": "new" } } ``` {% /code %} +**Error Response:** `400 Bad Request` + +Returned when required parameters are missing: + +{% code language="json" showLineNumbers=true %} + +```json +{ + "error": "filename is missing, file_size is missing, content_type is missing" +} +``` + +{% /code %} + **Error Response:** `422 Unprocessable Entity` -If the file is not found in storage, returns: +Returned when the file doesn't exist in S3 or validation fails: + +{% code language="json" showLineNumbers=true %} + +```json +{ + "error": "File not found in S3: uploads/binary_app/package/123/MyApp-v1.2.3.apk" +} +``` + +{% /code %} {% code language="json" showLineNumbers=true %} ```json { - "error": "File not found: uploads/binary_app/123/MyApp-v1.2.3.apk" + "error": "Validation failed: File size exceeds the maximum allowed size of 1GB" } ```