Merge branch 'fj-42685-extend-project-export-endpoint' into 'master'

Extend API for exporting a project with direct upload URL

Closes #42685

See merge request gitlab-org/gitlab-ce!17686

1 files changed, 17 insertions, 2 deletions

diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md
index de5207fc5e4..5467187788a 100644
--- a/doc/api/project_import_export.md
+++ b/doc/api/project_import_export.md
@@ -8,6 +8,14 @@
 
 Start a new export.
 
+The endpoint also accepts an `upload` param. This param is a hash that contains
+all the necessary information to upload the exported project to a web server or
+to any S3-compatible platform. At the moment we only support binary
+data file uploads to the final server.
+
+If the `upload` params is present, `upload[url]` param is required.
+ (**Note:** This feature was introduced in GitLab 10.7)
+
 ```http
 POST /projects/:id/export
 ```
@@ -16,9 +24,12 @@ POST /projects/:id/export
 | --------- | -------------- | -------- | ---------------------------------------- |
 | `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 | `description`      | string | no | Overrides the project description |
+| `upload`      | hash | no | Hash that contains the information to upload the exported project to a web server |
+| `upload[url]`      | string | yes      | The URL to upload the project |
+| `upload[http_method]`      | string | no      | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT` |
 
 ```console
-curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "description=Foo Bar" https://gitlab.example.com/api/v4/projects/1/export
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/export --data "description=FooBar&upload[http_method]=PUT&upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd"
 ```
 
 ```json
@@ -43,7 +54,11 @@ GET /projects/:id/export
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/export
 ```
 
-Status can be one of `none`, `started`, or `finished`.
+Status can be one of `none`, `started`, `after_export_action` or `finished`. The
+`after_export_action` state represents that the export process has been completed successfully and
+the platform is performing some actions on the resulted file. For example, sending
+an email notifying the user to download the file, uploading the exported file
+to a web server, etc.
 
 `_links` are only present when export has finished.