Uploading new builds programmatically

You can upload new builds for your apps programmatically.
Tip: To programmatically upload new builds, you must be assigned the participant role in MobileFirst Quality Assurance. For more information about the roles, see Managing participants.

About this task

You can upload a build artifact (either a mobile application binary file or a symbol file for iOS) to the MobileFirst Quality Assurance server for an existing mobile application. After the application binary is uploaded, you can notify testers that a new version of the build is available. By using the upload and distribute APIs, you can integrate MobileFirst Quality Assurance into a Continuous Build and Integration process to distribute a mobile application to a set of testers. The APIs are surfaced as a set of RESTful web services; you can call the APIs programmatically from various programming languages and tools.
Updating and distributing a build is a three-step process:
  1. Request a location to upload the build artifact. This request returns a URL location to upload the build artifact.
  2. Upload the build artifact by using the URL upload location that is returned in step 1. This request provides information about the uploaded artifact, including the installer ID if the build artifact is installable.
  3. Optional. Distribute the build to a group of testers by using the installer ID from step 2.
Table 1. Upload and distribute APIs.
Tip: If you are using a secure server, you must use HTTPS as the protocol; otherwise, use HTTP. By default, MobileFirst Quality Assurance is configured to support HTTPS. You can change the server configuration to support HTTP and disable HTTPS. For more information about configuring HTTPS, see Configuring the server to use HTTPS.
API Request Response Return codes
Create Artifact Metadata
Prepares the upload URL for the new artifact.
 Request for the upload URL:
POST  https://{mqa-server-address}/api/v1/applications/{application-id}/artifacts/
Where:
mqa-server-address
The address for the MobileFirst Quality Assurance server.
application-id
The ID of the application that the build artifact is associated with.
Tip: When you are logged in to MobileFirst Quality Assurance and viewing the application in a browser, you can determine the application ID by examining the URL. The application ID is the number that immediately follows "application" in the URL. For example, the following overview page has an application ID of 2: 
https://{mqa-server-address}/applications/2/dashboard/
The following header is used:
Key Value
Authorization basic_authentication_value 
{
"upload_url": "{upload_url}"
}
Note: You can use this generated upload URL once only to upload an artifact. Use the POST request with a content type of multipart/form-data to upload the build. Attach the artifact file to the field named resource.
  • 201 Artifact upload URL was successfully generated
  • 400 Bad request
  • 403 Forbidden (if the user does not have permission to add the resource)
Upload Artifact
Uploads an artifact to the generated upload URL.
 Refer to the URL that was returned from the request in Create Artifact Metadata. That URL can only be used once. Request to upload the build artifact:
POST URL_returned_from_Create_Artifact_metadata
The following content is included in the body of the request:
Key Value
resource filename
The following header is used:
Key Value
Authorization basic_authentication_value 
{
  "name": "{name}",
  "title": "{title}",
  "url": "{url}",
  "supported": {supported},
  "number": "{number}",
  "download_url": "{download_url}",
  "package": "{package}",
  "type": "installer",
  "id": {id},
  "icon": "{icon}"
}
  • 200 Artifact was successfully uploaded
  • 400 Bad request
  • 403 Forbidden (if the user does not have permission to add the resource)
Distribute Build
Distributes the application version to the specified users.
 Request to distribute the application version:
POST https://{mqa-server-address}/api/v1/applications/{application-id}/distributions/
The following headers are used:
Key Value
Authorization basic_authentication_value
Content-Type application/json
The following JSON parameters are used:
installer
Required. The ID of the installer with the associated artifact to distribute.
individuals
Individuals, groups, or both are required. The list of emails to use for the distribution notification.
groups
Groups, individuals, or both are required. The names of the email groups to use for the distribution notification.
message
Optional. The additional message to attach to the distribution notification.
license
Optional. The non-disclosure agreement for the product.
 
{
  "id": {id},
  "url": "{url}",
  "created_at": "{created_at}",
  "modified_at": "{modified_at}",
  "application": "{application}",
  "installer": "{installer}",
  "created_by": "{created_by}",
  "message": "{message}",
  "emails": [
    "{email}",
    "{email}"
  ]
}
  • 200 Distribution scheduled successfully.
  • 400 Bad request

Procedure

Use the MobileFirst Quality Assurance upload and distribute APIs to upload and distribute your .apk, .api, and symbolic files:

Tip: In the following code snippets, the Linux curl command is used to demonstrate how to use the MobileFirst Quality Assurance APIs. The responses that are shown are examples and the answers change with each request.

  1. POST to get the upload URL: 
    curl -k -X POST -u user1@email.com:password https://{mqa-server-address}/api/v1/applications/{application-id}/artifacts/
    The following response is returned:
    {"upload_url": "https://{mqa-server-address}/api/v1/resources/artifact/upload/?signature=eyJhcHBsaWNhdGlvbiI6IDE1LCAiX3V1aWQiOiAiMWQ1YmM1YjIxMTZjOWJkYzE5ZWEzOGNiNTBiYzk1YjI0ODRhZDYzYyIsICJfZXhwaXJlc19vbiI6IDE0MDgyMDcxODMsICJjcmVhdGVkX2J5IjogM30%3D_e3bfad26ad83a064da06a56293c447dc52d7606f040710fda82adb824f750747"}
  2. POST to upload the build: 
    curl -k -u user1@email.com:password -F "resource=@/{build-file}" {upload_url}
    Where:
    • build-file is the location of the .apk, .api, or symbolic file.
    • upload_url is the URL that was returned from the response in the step 1. For example:
      curl -k -u user1@email.com:password -F "resource=@/root/Downloads/MyAppBuildFile.ipa"
https://{mqa-server-address}/api/v1/resources/artifact/upload/?signature=eyJhcHBsaWNhdGlvbiI6IDE1LCAiX3V1aWQiOiAiMWQ1YmM1YjIxMTZjOWJkYzE5ZWEzOGNiNTBiYzk1YjI0ODRhZDYzYyIsICJfZXhwaXJlc19vbiI6IDE0MDgyMDcxODMsICJjcmVhdGVkX2J5IjogM30%3D_e3bfad26ad83a064da06a56293c447dc52d7606f040710fda82adb824f750747
    The following response is returned:
    {
    "name": "6.0",
    "package": "com.example.analyzer",
    "url": "/api/v1/applications/{applications-id}/installers/",
    "title": "com.example.analyzer",
    "number": "6",
    "download_url": "/resources/artifact/download/?signature=eyJfZXhwaXJlc19vbiI6IG51bGwsICJvYmpfaWQiOiAzOX0%3D_6dd3c3bcf93bb12c7cc8128b975ad9e7ddf511a11170a66c38acfe389bb6488d",
    "type": "installer",
    "id": 38,
    "icon": "/application/icon/download/?signature=eyJfZXhwaXJlc19vbiI6IG51bGwsICJvYmpfaWQiOiAyMH0%3D_4034a3ea3cc7b1fdcf13d9ef10a942ffcc7b6731e1db9630adce8f0de3dea297"
}
  3. Optional: POST to distribute the build. Add the ID of the installer in the command: 
    curl -k -X POST -H "Content-Type: application/json" -H "Authorization: Basic xxx" 
-u user1@email.com:password https://{mqa-server-address}/api/v1/applications/{applications-id}/distributions/ 
-d '{"installer": 38, "message": "Build Dist from command line with short installer", "individuals": [ "user1@email.com", "user2@email.com"] }'
Parent topic: Managing builds
Related tasks:
Uploading new builds from the user interface