Skip to content

Commit c98bbda

Browse files
gmorgachevgmorgachev
authored
Merge pull request #62 from product-science/gm/upload-build
Upload API docs
2 parents 7e39a9d + 19fbd80 commit c98bbda

File tree

2 files changed

+186
-1
lines changed

2 files changed

+186
-1
lines changed

‎docs/mobile/integration/upload-api.md

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Upload API
2+
3+
## Overview
4+
5+
This page describes the HTTP API for uploading instrumented builds to the Product Science Tool.
6+
7+
### HTTP API
8+
9+
Host: `productscience.app`
10+
Protocol: `HTTPS`
11+
Content type: `application/json`
12+
Charset: `utf-8`
13+
14+
To access the API endpoints, you must supply your `productscience.token` from the `productscience.properties` or (`productscience.yaml`) file as an Authorization header. For instance:
15+
16+
```
17+
Authorization: Bearer {YOUR_TOKEN}
18+
```
19+
20+
## API
21+
22+
### 1. Submit build metadata and obtain upload URL
23+
24+
Call this endpoint when your build file is ready.
25+
26+
#### Request
27+
28+
29+
```
30+
POST /api/v1/projects/{projectName}/builds
31+
```
32+
33+
JSON body with parameters:
34+
35+
- **`buildType`** (required) – `INSTRUMENTED_APK` (for iOS also)
36+
- **`buildFileName`** (required) – file name, e.g. `app-play-release.apk`
37+
- **`name`** – arbitrary name to distinguish the build, e.g. `release-5.2.8`
38+
- **`description`** – arbitrary build description
39+
- **`sourceControlId`** – VCS commit, e.g. git commit hash
40+
- **`sourceControlIsoTimestamp`** – VCS commit timestamp in ISO 8601 format. To retrieve the timestamp in Git, you can use the following shell command: `git show -s --format='%cI' <commit-hash>`
41+
42+
Example:
43+
44+
```json
45+
{
46+
"contextId": "28",
47+
"buildType": "APK",
48+
"buildFileName": "app-play-release.apk",
49+
"name": "v5.2.8",
50+
"description": "Arbitrary description",
51+
"sourceControlId": "e3c0fedc625094db1cbb2823fd425b51ddc0932e",
52+
"sourceControlIsoTimestamp": "2024-03-07T14:55:43.540Z"
53+
}
54+
```
55+
56+
#### Response
57+
58+
JSON body with parameters:
59+
60+
- **`uploadSpec`** (required) – metadata to upload build to a storage
61+
* **`method`** (required) – HTTP method
62+
* **`url`** (required) – URL
63+
* **`headers`** (required) – map of HTTP headers
64+
- **`build`** (required) – build metadata
65+
* **`id`** (required) – build ID number
66+
* **`contextId`** (required) – upload context ID obtained in step 1
67+
* **`buildType`** (required) – `INSTRUMENTED_APK`
68+
* **`buildFileName`** (required) – file name, e.g. `app-play-release.apk`
69+
* **`name`** – arbitrary name to distinguish the build, e.g. `release-5.2.8`
70+
* **`description`** – arbitrary build description
71+
* **`sourceControlId`** – VCS commit, e.g. git commit hash
72+
* **`sourceControlIsoTimestamp`** – VCS commit timestamp in ISO 8601 format
73+
* **`uploadState`** – `UPLOADING` or `FINISHED` or `FAILED`
74+
* **`dateCreated`** – build creation timestamp
75+
76+
Example:
77+
78+
```json
79+
{
80+
"uploadSpec": {
81+
"method": "PUT",
82+
"url": "https://storage.googleapis.com/some/path?someParams=someValue",
83+
"headers": {
84+
"Content-Type": "application/octet-stream",
85+
"X-Goog-Content-Length-Range": "0,1073741824"
86+
}
87+
},
88+
"build": {
89+
"id": 70,
90+
"contextId": 28,
91+
"buildType": "INSTRUMENTED_APK",
92+
"buildFileName": "app-play-release.apk",
93+
"name": "v5.2.8",
94+
"description": "Arbitrary description",
95+
"sourceControlId": "e3c0fedc625094db1cbb2823fd425b51ddc0932e",
96+
"sourceControlIsoTimestamp": "2024-03-07T14:55:43.540Z",
97+
"dateCreated": "2024-03-08T14:13:33.143Z",
98+
"uploadState": "UPLOADING"
99+
}
100+
}
101+
```
102+
103+
### 2. Upload file to the obtained URL
104+
105+
Use `uploadSpec` object from the previous response to upload a file as `application/octet-stream`.
106+
107+
```
108+
{uploadSpec.method} {uploadSpec.url}
109+
{uploadSpec.hearder1}: {uploadSpec.header1Value}
110+
{uploadSpec.hearder2}: {uploadSpec.header2Value}
111+
Content-Length: {YOUR_FILE_LENGTH}
112+
113+
{YOUR_FILE_BINARY_DATA}
114+
```
115+
116+
## cURL example
117+
118+
### 1. Submit build metadata and obtain upload URL
119+
120+
Request:
121+
122+
```shell
123+
curl -X "POST" "https://test.productscience.app/api/v1/projects/{projectName}/builds" \
124+
-H 'Authorization: Bearer {YOUR_TOKEN}' \
125+
-H 'Content-Type: application/json; charset=utf-8' \
126+
-d $'{
127+
"buildType": "INSTRUMENTED_APK",
128+
"buildFileName": "app-play-release.apk",
129+
"name": "v5.2.8"
130+
"description": "Arbitrary description",
131+
"sourceControlId": "e3c0fedc625094db1cbb2823fd425b51ddc0932e",
132+
"sourceControlIsoTimestamp": "2024-03-07T14:55:43.540Z",
133+
}'
134+
```
135+
136+
Response:
137+
138+
```
139+
HTTP/1.1 200 OK
140+
Content-Type: application/json
141+
Content-Length: 1430
142+
```
143+
```json
144+
{
145+
"uploadSpec": {
146+
"method": "PUT",
147+
"url": "https://storage.googleapis.com/some/path?someParams=someValue",
148+
"headers": {
149+
"Content-Type": "application/octet-stream",
150+
"X-Goog-Content-Length-Range": "0,1073741824"
151+
}
152+
},
153+
"build": {
154+
"id": 70,
155+
"contextId": 28,
156+
"buildType": "INSTRUMENTED_APK",
157+
"buildFileName": "app-play-release.apk",
158+
"name": "v5.2.8",
159+
"description": "Arbitrary description",
160+
"sourceControlId": "e3c0fedc625094db1cbb2823fd425b51ddc0932e",
161+
"sourceControlIsoTimestamp": "2024-03-07T14:55:43.540Z",
162+
"dateCreated": "2024-03-08T14:13:33.143Z",
163+
"uploadState": "UPLOADING"
164+
}
165+
}
166+
```
167+
168+
### 2. Upload file to the obtained URL
169+
170+
Request:
171+
172+
```shell
173+
curl -X "PUT" "https://storage.googleapis.com/some/path?someParams=someValue" \
174+
-H 'Content-Type: application/octet-stream' \
175+
-H 'X-Goog-Content-Length-Range: 0,1073741824' \
176+
--data-binary "@{FILE_PATH}"
177+
```
178+
179+
Response:
180+
181+
```
182+
HTTP/1.1 200 OK
183+
Content-Length: 0
184+
```

‎mkdocs.yml

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ nav:
1212
- CodeTuner for Cloud:
1313
- Overview: cloud/overview.md
1414
- Integration:
15-
- Common: cloud/integration/integration.md
15+
- Common: cloud/integration/integration.md
1616
- JVM Agent: cloud/integration/jvm-agent.md
1717
- Usage: cloud/usage.md
1818
- Release Notes:
@@ -30,6 +30,7 @@ nav:
3030
- Build / Xcode: mobile/integration/ios/xcode.md
3131
- Build / Bazel: mobile/integration/ios/bazel.md
3232
- App Distribution: mobile/integration/ios/distribution.md
33+
- Upload API: mobile/integration/upload-api.md
3334
- Device Set-Up:
3435
- Android: mobile/device-set-up/android.md
3536
- iOS: mobile/device-set-up/ios.md

0 commit comments

Comments
 (0)