Skip to content

Latest commit

 

History

History
1196 lines (956 loc) · 24.5 KB

rest-api.md

File metadata and controls

1196 lines (956 loc) · 24.5 KB
id title sidebar_label
rest-api
REST API
REST API

import useBaseUrl from '@docusaurus/useBaseUrl'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

In this document you can find the reference for the Sauce Mobile App Distribution REST API. This API allows the developer to access and interact with Sauce Mobile App Distribution data remotely.

Getting Started

Getting started with the REST API can be done via the command line with any programming language. Let's begin with an example: by listing all our projects.

Supported Public Cloud endpoints:

US-East-1

curl -u "[email protected]:00001234cafecafe" "https://mobile.saucelabs.com/api/1/projects/"

EU-Central-1 (Access keys are different in each Data Center)

curl -u "[email protected]:coffee00001234" "https://mobile.eu-central-1.saucelabs.com/api/1/projects/"

Previous Sauce Mobile App Distribution US-East endpoint:

curl -u "[email protected]:00001234cafecafe" "https://api.testfairy.com/api/1/projects/"

A project is either an iOS app or an Android app (two apps with the same package name but on different platforms are considered two projects.)

In the example above, you can see that our user is [email protected] and the API key is 0001234cafecafe. This user authentication token is required for all requests to the REST server.

Your API key is private, do not share it or post it on public code repositories or forums. To find your API key, refer to your preferences page.

Projects

Get All Projects

GET/api/1/projects/

Returns a list of all projects (iOS and Android apps) in this account.

Responses

200 Success. 
{
    "status": "ok",
    "projects": [
        {
            "id": "6905338",
            "self": "/projects/19-groupshot",
            "name":"GroupShot",
            "packageName":"com.groupshot",
            "platform":"Android",
            "icon":"[URL TO APP ICON]"
        }
    ]
}

Builds

Get All Builds in a Project

GET/api/1/projects/{project-id}/builds/

Get all builds in a specific project. Each build is a distinct version that is either uploaded or created by the Sauce Mobile App Distribution SDK.

Responses

200 Success. 
{
    "status": "ok",
    "builds": [
        {
            "id":"8830728",
            "self":"/projects/6806100-myapplication/builds/8830728",
            "projectId":"6806100",
            "appName":"My Application",
            "appVersion":"DemoApp",
            "appVersionCode":"20",
            "appDisplayName":"My Application - DemoApp (20)",
            "iconUrl":"[APP ICON URL]",
            "appUrl":"[URL TO APK OR IPA FILE]",
            "sessions":6,
            "crashes":0,
            "testers":0,
            "feedbacks":0,
            "downloads":1,
            "uploadedAt":"2019-04-04 16:03:15",
            "uploadedVia":"[UPLOAD DETAILS]",
            "hasTestFairySdk":true,
            "insightsEnabled":true,
            "videoEnabled":true
        }
    ]
}

Get Metadata for a Specific Build

GET/api/1/projects/{project-id}/builds/{build-id}

Get a specific build of a specific project. Query the /api/1/projects/{project-id} API for a list of available builds.

Responses

200 Success. 
{
    "status": "ok",
    "build": {
        "id":"8830728",
        "self":"/projects/6806100-myapplication/builds/8830728",
        "projectId":"6806100",
        "appName":"My Application",
        "appVersion":"DemoApp",
        "appVersionCode":"20",
        "appDisplayName":"My Application - DemoApp (20)",
        "iconUrl":"[APP ICON URL]",
        "appUrl":"[URL TO APK OR IPA FILE]",
        "sessions":6,
        "crashes":0,
        "testers":0,
        "feedbacks":0,
        "downloads":1,
        "uploadedAt":"2019-04-04 16:03:15",
        "uploadedVia":"[UPLOAD DETAILS]",
        "hasTestFairySdk":true,
        "insightsEnabled":true,
        "videoEnabled":true
    }
}

Delete a Specific Build

DELETE/api/1/projects/{project-id}/builds/{build-id}

Delete a specific build. When all builds of a project are deleted, the project itself is removed from /api/1/projects API. When deleting a build, all of its artifacts (IPA/APK files), recorded sessions, and crashes are also deleted.

Responses

200 Success. 
{
    "status": "ok"
}

Copy a Specific Build to a Folder

POST/api/1/projects/{project-id}/builds/{build-id}/copy

Use this endpoint to copy a specific build to a specified folder. You can either create a new folder or copy the build to an existing one.

Parameters

folder_name

| REQUIRED | STRING |

The name or path of the target folder. Examples: Folder1 or /Project1/Folder1.
app_name

| OPTIONAL | STRING |

Defines a new name for the application when copying the build to the target folder.
If specified, the build is renamed to the given app_name.
If not specified, the original application name is preserved.

Responses

200 Success. 
{
    "status": "ok",
    "build_id": "1000",
    "folder_path": "/Project1/Folder1",
    "app_name": "My Application"
}

Download the Uploaded Artifact

GET/api/1/projects/{project-id}/builds/{build-id}/download/

Downloads the binary file uploaded to Sauce Mobile App Distribution.

Responses

200 Success.

Invite Additional Testers to Build

POST/api/1/projects/{project-id}/builds/{build-id}/invites/

Invite one or more tester groups to this specific build. You can optionally send out an email.

Parameters

groups

| REQUIRED | STRING |

Comma separated list of tester group names or id.
comment

| OPTIONAL | STRING |

Additional text that will be added to the email, such as release notes.
notify

| OPTIONAL | STRING |

Set to on to send out an email to each tester. Default value is off.

Responses

200 Success.

List All Recorded Sessions in Build

GET/api/1/projects/{project-id}/builds/{build-id}/sessions/

Get metadata for all sessions recorded for a specific build.

Responses

200 Success. 
{
    "status": "ok",
    "sessions": [
        {
            "id": 1,
            "self": "/projects/2197059-demoapp/builds/4867553/sessions/1",
            "startTime": "2017-01-22 16:42:40",
            "duration": "15:01",
            "testerEmail": "[email protected]",
            "device": "Samsung - Samsung Galaxy S8",
            "ipAddress": "23.100.122.175",
            "crashed": false,
            "countryName": "United States",
            "countryCode": "us"
        }
    ]
}

Get Session Data, Events and Logs

GET/api/1/projects/{project-id}/builds/{build-id}/sessions/{session-id}

Get metadata (and optionally data) for a specific session.

Parameters

fields

| OPTIONAL | STRING |

Possible values: meta, logs, events. The default value is meta. Use events to load all events, screenshots, touches, and other metrics. Use logs to fetch only logs. When loading logs, the response is application/text.

Responses

200 Success. 
{
    "status": "ok",
    "session": {
        "id":4426273741,
        "sessionStartTime":"2019-05-20 09:05:30",
        "duration":"00:27",
        "testerEmail":"[email protected]",
        "device":"Xiaomi - Redmi S2",
        "ipAddress":"84.94.200.136",
        "crashed":false,
        "identity":{
            "correlationId":"[email protected]",
            "attr3":"three",
            "attr4":"four",
            "attr1":"High",
            "attr2":"1.0",
            "attr5":"Version 1.0"
    }
}

Testers

List All Testers

GET/api/1/testers

List all testers in this account.

Responses

200 Success. 
{
    "status": "ok",
    "testers": [
        {
            "email":"[email protected]",
            "groups":[{
                id: 100,
                name: "friends"
            }]
        },
        {
            "email":"[email protected]",
            "groups":[{
                id: 100,
                name: "friends"
            }, {
                id: 200,
                name: "family"
            }]
        }
    ]
}

Add a New Tester

POST/api/1/testers/

Add a new tester to account. Optionally can add them to a group.

Parameters

email

| OPTIONAL | STRING |

One or more emails, separated by commas, to add to your account.
group

| OPTIONAL | STRING |

Assign tester or testers to this tester-group. It creates one if no such group exists. Default value: none.
notify

| OPTIONAL | STRING | INTEGER

Pass notify=on or notify=1 to send a welcome email when inviting this tester.
The email will use the "Tester Welcome Email" template, which can be customized.
By default, email sending is disabled.

Responses

200 Success. 
{
    "status": "ok"
}

Block a Tester

POST/api/1/testers/{tester-id}/block/

Blocks a single tester. They cannot download the apps they are invited to. However, the data stays. You can later unblock this tester or delete them completely.

Responses

200 Success. 
{
    "status": "ok"
}

Unblock a Tester

DELETE/api/1/testers/{tester-id}/block/

Unblock a single tester. Their invitations are restored. If the user is already unblocked, then nothing happens.

Responses

200 Success. 
{
    "status": "ok"
}

Delete a Tester

DELETE/api/1/testers/{tester-id}

Delete a single tester, remove them from any tester-groups they might be in, and invalidate all invitations that are sent.

Responses

200 Success. 
{
    "status": "ok"
}

Add a Tester to a Group

POST/api/1/testers/groups/{group-id}

Add a single or multiple testers to a specific group.

Parameters

email

| REQUIRED | STRING |

One or more email addresses, separated by commas, to be added to a group.

Responses

200 Success. 
{
  "status": "ok",
  "testers": [
    {
      "email": "[email protected]"
    },
    {
      "email": "[email protected]"
    }
  ]
}

Remove a Tester from a Group

DELETE/api/1/testers/groups/{group-id}

Remove a single or multiple testers from a specific group.

**Note:** Groups without any members will be discarded.

Parameters

email

| REQUIRED | STRING |

One or more email addresses, separated by commas, to be removed from a group.

Responses

200 Success. 
{
  "status": "ok",
  "testers": [
    {
      "email": "[email protected]"
    },
    {
      "email": "[email protected]"
    }
  ]
}

List All Tester groups

GET/api/1/testers/groups

List all tester groups in this account.

Responses

200 Success. 
{
  "status": "ok",
  "groups": [
    {
      "id": 14,
      "name": "group1",
      "testers": [
        [
          {
            "email": "[email protected]"
          },
          {
            "email": "[email protected]"
          },
          {
            "email": "[email protected]"
          }
        ]
      ]
    },
    {
      "id": 39,
      "name": "group2",
      "testers": [
        [
          {
            "email": "[email protected]"
          }
        ]
      ]
    }
  ]
}

Create a Tester Group

POST/api/1/testers/groups

Create a new tester group

Parameters

groupName

| REQUIRED | STRING |

Specify a group name.

Responses

200 Success. 
{
    "status": "ok",
    "id": "40",
    "name": "group3"
}

Feedbacks

Get Latest Recorded Feedbacks

GET/api/1/feedbacks/

Get metadata for 100 of the latest feedbacks recorded.

Responses

200 Success. 
{
    "status": "ok",
    "feedbacks": [
        {
            "recorded_at": "2018-08-01 04:14:46",
            "text": "Feedback working",
            "feedbackId": "54321",
            "screenshotUrl": "https://s3.amazonaws.com/feedback.jpg",
            "buildId": "1234",
            "projectId": "23456",
            "recordedAt":"2018-08-01 14:14:46",
            "source": "shake",
            "reported_by": "[email protected]",
            "session_id": "8765432"
        }
    ]
}

Audits

Get Recent Audit Trail Items

GET/api/1/audits

Get recent audit trail items.

Responses

200 Success. 
{
    "status": "ok",
    "audits": [
        {
            "id": 23534603,
            "timestamp": "2020-04-21 02:31:54",
            "ipAddress": "54.235.41.91",
            "eventType": "download_app",
            "eventData": {
                "projectId": 6833287,
                "buildId": 9087976,
                "appName": "MyApp",
                "appVersion": "1.0 (10)",
                "testerEmail": "[email protected]",
                "filesize": 31348
            }
        }
    ]
}

Permissions

Get the List of Admins and Their Permissions

GET/api/1/cpanel/permissions/

Get the list of admins in the account and their permissions.

Responses

200 Success. 
{
    "status": "ok",
    admins:
    [
        {
            email: "[email protected]",
            role: "account-owner",
            permissions: [
                "*:rw"
            ]
        },
        {
            email: "[email protected]",
            role: "account-manager",
            permissions: [
                "*:rw"
            ]
        },
        {
            email: "[email protected]",
            role: "admin",
            permissions: [
                "*:rw"
            ]
        },
        {
            email: "[email protected]",
            role: "admin",
            permissions: [
                "16527:rw",
                "16517:rw",
                "69237:r"
            ]
        },
    ]
}

Webhooks

List All Webhooks

GET/api/1/webhooks/

List all webhooks in this account.

Responses

200 Success. 
{
    "status":"ok",
    "webhooks":[
        {
            "id":12,
            "status":"0",
            "name":"Slack Webhook @vijay",
            "url":"https://hooks.slack.com/services/",
            "actions":"crash,feedback,upload,new-udid",
            "projectIds":"12345,45643"
        }
    ]
}

Add a New Webhook

POST/api/1/webhook/

Add a new webhook to the account.

Parameters

webhook-name

| REQUIRED | STRING |

The name of the webhook.
webhook-url

| REQUIRED | STRING |

The URL for the webhook.
webhook-status

| OPTIONAL | STRING |

Enables or disables the webhook. The values are: true, false. Default value is false.
actions

| OPTIONAL | STRING |

Comma separated list of actions. Options include: crash, feedback, upload, new-udid.
webhook-project-ids

| OPTIONAL | STRING |

Comma separated list of project IDs.

Responses

200 Success. 
{
    "status": "ok"
}

Get a Single Webhook

GET/api/1/webhook/{webhook-id}/

Returns a single webhook.

Responses

200 Success. 
{
    "status": "ok",
    "webhook": {
        "id":12,
        "status":"0",
        "name":"Slack Webhook @vijay",
        "url":"https://hooks.slack.com/services/",
        "actions":"crash,feedback,upload,new-udid",
        "projectIds":"12345,45643"
    }
}

Modify a Webhook

POST/api/1/webhook/{webhook-id}/

Modifies a single webhook.

Parameters

webhook-name

| REQUIRED | STRING |

The name of the webhook.
webhook-url

| REQUIRED | STRING |

The URL for the webhook.
webhook-status

| OPTIONAL | STRING |

Enables or disables the webhook. The values are: true, false. Default value is false.
actions

| OPTIONAL | STRING |

Comma separated list of actions. Options include: crash, feedback, upload, new-udid.
webhook-project-ids

| OPTIONAL | STRING |

Comma separated list of project IDs.

Responses

200 Success. 
{
    "status": "ok"
}

Delete a Webhook

DELETE/api/1/webhook/{webhook-id}/

Deletes a single webhook.

Responses

200 Success. 
{
    "status": "ok"
}