Skip to content

Commit c5befcd

Browse files
asteiner-swisstopoasteiner-swisstopo
authored
Merge pull request #56 from geoadmin/feat-PB-1969-improve-stac-api-docs
PB-1969 Improve STAC API docs #patch
2 parents c927875 + 130ace0 commit c5befcd

File tree

6 files changed

+63
-805
lines changed

6 files changed

+63
-805
lines changed

‎.vitepress/config.mts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ function downloadDataItems(): DefaultTheme.SidebarItem[] {
211211
},
212212
{ text: 'Caching', link: '/docs/stac-api/caching' },
213213
{ text: 'Item Expiration', link: '/docs/stac-api/item-expiration' },
214-
{ text: 'Migrate v0.9 to v1.0', link: '/docs/stac-api/migrate09-10' },
214+
{ text: 'Migrate v0.9 to v1', link: '/docs/stac-api/migrate09-10' },
215215
{
216216
text: 'API Specs',
217217
link: 'https://data.geo.admin.ch/api/stac/static/spec/v1/api.html',

‎docs/stac-api/asset-upload.md‎

Lines changed: 44 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,16 @@ Uploading an asset file via the STAC API involves three main steps:
3939

4040
2. **Upload file parts:**
4141

42-
Use the presigned URLs returned in step 1 to [upload each part](https://data.geo.admin.ch/api/stac/static/spec/v1/apitransactional.html#tag/Asset-Upload-Management/operation/uploadAssetFilePart). You may upload parts in parallel.
42+
Use the presigned URLs returned in step 1 to [upload each part](https://data.geo.admin.ch/api/stac/static/spec/v1/apitransactional.html#tag/Asset-Upload-Management/operation/uploadAssetFilePart).
4343

4444
<ApiCodeBlock url="/storage-prefix/{presignedUrl}" method="PUT" />
4545

46+
You may upload parts in parallel. It is possible to retry a failed upload.
47+
48+
:::warning
49+
Presigned URLs expire within three hours, so the upload must be completed before that.
50+
:::
51+
4652
<br/>
4753

4854
3. **Complete the upload:**
@@ -126,7 +132,7 @@ If you have recurrent asset uploads, you need to have proper error handling to p
126132
The number of retries should be adjusted based on the upload frequency.
127133

128134
- For low-frequency uploads (e.g., daily), it is advisable to implement at least 3 retries, using exponential backoff time between retries.
129-
- For high-frequency uploads, you may choose to skip retries and instead cancel the current upload, relying on the next scheduled upload as a fallback.
135+
- For high-frequency uploads, you may choose to skip retries and instead abort the current upload, relying on the next scheduled upload as a fallback.
130136

131137
:::tip GLOSSARY
132138

@@ -136,58 +142,58 @@ The number of retries should be adjusted based on the upload frequency.
136142

137143
The following example illustrates best practices for handling errors during repeated asset uploads.
138144

139-
1. **Create Asset Upload**
145+
1. **Create Asset Upload**
140146

141-
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads" method="POST" />
147+
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads" method="POST" />
142148

143-
Possible Responses:
149+
Possible Responses:
144150

145-
| HTTP Response | Action Required |
146-
| ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
147-
| `201 OK` | Continue to step 2. |
148-
| `400 Bad Request - "Upload already in progress"` | Abort the existing upload (see below), then restart step 1. |
149-
| `400 Bad Request - other errors` | Cancel upload. Analyze and correct your request before retrying. |
150-
| `500 Internal Server Error` | Cancel upload. Report to service administrator (retry usually useless). |
151-
| `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Retry later. Adjust wait time based on upload rate (minimum 100ms). |
151+
| HTTP Response | Action Required |
152+
| ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
153+
| `201 OK` | Continue to step 2. |
154+
| `400 Bad Request - "Upload already in progress"` | Abort the existing upload (see below), then restart step 1. |
155+
| `400 Bad Request - other errors` | Cancel upload. Analyze and correct your request before retrying. |
156+
| `500 Internal Server Error` | Cancel upload. Report to service administrator (retry usually useless). |
157+
| `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Retry later. Adjust wait time based on upload rate (minimum 100ms). |
152158

153-
If the response is `{"description": "Upload already in progress", "code": 400}`, you should abort the upload.
159+
If the response is `{"description": "Upload already in progress", "code": 400}`, you should abort the upload.
154160

155-
**a.** Get the `upload_id` of the upload marked in progress via:
161+
**a.** Get the `upload_id` of the upload marked in progress via:
156162

157-
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads?status=in-progress" method="GET" />
163+
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads?status=in-progress" method="GET" />
158164

159-
**b.** Abort the upload:
165+
**b.** Abort the upload:
160166

161-
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads/{upload_id}/abort" method="POST" />
167+
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads/{upload_id}/abort" method="POST" />
162168

163-
**c.** Restart the asset upload.
169+
**c.** Restart the asset upload.
164170

165-
2. **Upload the parts via the presigned URL from step 1**
171+
2. **Upload the parts via the presigned URL from step 1**
166172

167-
<ApiCodeBlock url="{presigned_url}" method="PUT" />
173+
<ApiCodeBlock url="{presigned_url}" method="PUT" />
168174

169-
Possible Responses:
175+
Possible Responses:
170176

171-
| HTTP Response | Action Required |
172-
| ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
173-
| `200 OK` | Continue to step 3. |
174-
| `400 Bad Request` | Abort upload |
175-
| `500 Internal Server Error` | Cancel upload. Report to service administrator (retry usually useless). |
176-
| `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Retry step 2 after a short wait (minimum 100ms). |
177+
| HTTP Response | Action Required |
178+
| ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
179+
| `200 OK` | Continue to step 3. |
180+
| `400 Bad Request` | Abort upload |
181+
| `500 Internal Server Error` | Cancel upload. Report to service administrator (retry usually useless). |
182+
| `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Retry step 2 after a short wait (minimum 100ms). |
177183

178-
3. **Complete the upload**
184+
3. **Complete the upload**
179185

180-
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads/{upload_id}/complete" method="POST" />
186+
<ApiCodeBlock url="https://data.geo.admin.ch/api/stac/v1/collections/{collection}/items/{item}/assets/{asset}/uploads/{upload_id}/complete" method="POST" />
181187

182-
Possible Responses:
188+
Possible Responses:
183189

184-
| HTTP Response | Action Required |
185-
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
186-
| `200 OK` | Upload successful. |
187-
| `400 Bad Request` | Cancel upload |
188-
| `500 Internal Server Error` | Cancel upload. Report to service administrator (retry usually useless). |
189-
| `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Service is momentarily not available, wait a short moment, then retry the request. |
190+
| HTTP Response | Action Required |
191+
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
192+
| `200 OK` | Upload successful. |
193+
| `400 Bad Request` | Cancel upload |
194+
| `500 Internal Server Error` | Cancel upload. Report to service administrator (retry usually useless). |
195+
| `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Service is momentarily not available, wait a short moment, then retry the request. |
190196

191-
The following figure shows the flow of a multipart upload process.
197+
The following figure shows the flow of a multipart upload process.
192198

193-
<img src="../../static/service-stac-upload-process.svg" />
199+
<img src="../../static/service-stac-upload-process.svg" />

‎docs/stac-api/authentication.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Basic authentication and token authentication were removed in STAC API version `
1111

1212
## Session Authentication
1313

14-
Users can browse geodata in the "admin interface", a web-based UI available to selected user.
14+
Users can browse geodata in the "admin interface", a web-based UI available to selected users.
1515
Upon successful login, the service issues a session cookie that authenticates subsequent requests from the browser.
1616

1717
Session authentication is designed specifically for browser-based workflows and may not work with non-browser clients or all API endpoints.
@@ -23,7 +23,7 @@ JWT authentication is the recommended approach for API clients performing write
2323
JWT authentication involves two steps:
2424

2525
1. Obtain a JWT token from Amazon Cognito's [InitiateAuth API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html).
26-
2. Include the tokes in the HTTP `Authorization` header using the `Bearer` scheme as defined in [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).
26+
2. Include the token in the HTTP `Authorization` header using the `Bearer` scheme as defined in [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).
2727

2828
To obtain a JWT token, use Amazon Cognito’s InitiateAuth API by sending your username and password, along with your client ID. For example:
2929

‎docs/stac-api/compression.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,20 @@ Efficient compression reduces bandwidth usage and improves load times, especiall
55

66
## Compression During Download
77

8-
To optimize transfer speeds, files between 1 MB and 10 MB are automatically compressed during download.
8+
To optimize transfer speeds, files between 1 MB and 10 MB are automatically compressed during download if the client supports it.
99
The compression format - either GZIP (`gzip`) or Brotli (`br`) - is determined by the `Accept-Encoding` header sent with the request.
1010

11+
Files that are already stored in a compressed format are not compressed again during download.
12+
1113
Compression is only applied to standard media types supported by Amazon CloudFront.
1214
For details, refer to the CloudFront documentation on [serving compressed files](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/ServingCompressedFiles.html#compressed-content-cloudfront-file-types).
1315

1416
## Compression Before Upload
1517

16-
For files larger than 10 MB, it's recommended to use a [compressed media type](/docs/stac-api/supported-media).
17-
If that is not an option, you can either split the file into smaller parts or compress it manually.
18+
For files larger than 10 MB, we recommended to use a [compressed media type](/docs/stac-api/supported-media).
19+
20+
If you cannot use a compressed media type, compress the file yourself with `gzip` or `br`.
21+
To have the file delivered later in its compressed form, set the `content_encoding` parameter in the [multipart upload request](https://data.geo.admin.ch/api/stac/static/spec/v1/apitransactional.html#tag/Asset-Upload-Management/operation/createAssetUpload) accordingly.
22+
Client applications must support the selected compression format.
1823

19-
If you compress the file manually using `gzip` or `br`, you must set the `content_encoding` parameter inf the [multipart upload request](https://data.geo.admin.ch/api/stac/static/spec/v1/apitransactional.html#tag/Asset-Upload-Management/operation/createAssetUpload) accordingly.
20-
The file will then be delivered in its compressed form, as indicated by the `Content-Encoding` header.
21-
Client applications must be able to handle this compression format.
24+
If the file remains too large after compression, split it into smaller parts.

‎docs/stac-api/migrate09-10.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@
22
outline: [2, 3]
33
---
44

5-
# Changes and Migration from `v0.9` to `v1`
5+
# Migrate `v0.9` to `v1`
66

77
The new major release `v1` of the STAC API brings a number of additional features and fields and a few breaking changes with respect to `v0.9`.
8-
In order to highlight the changes we'll use the following example `item` and `asset` JSON objects to illustrate the differences.
98

10-
::: details Example `item` JSON
9+
In order to highlight the changes we'll use the following example `item` and `asset` JSON objects (compliant with `v0.9`) to illustrate the differences.
10+
11+
::: details Example `item` JSON (`v0.9`)
1112

1213
```json
1314
{
@@ -44,7 +45,7 @@ In order to highlight the changes we'll use the following example `item` and `as
4445
```
4546

4647
:::
47-
::: details Example `asset` JSON
48+
::: details Example `asset` JSON (`v0.9`)
4849

4950
```json
5051
{

0 commit comments

Comments
 (0)