From e861c3183fa207ba2ab3109f291cf9fe085ff0d2 Mon Sep 17 00:00:00 2001
From: Chris Roberts <croberts@hashicorp.com>
Date: Thu, 5 Nov 2020 09:23:39 -0800
Subject: [PATCH] Update API documentation to include direct

Adds Vagrant Cloud API documentation for using the direct upload
approach with proper curl and ruby examples.
---
 website/pages/vagrant-cloud/api.mdx | 83 +++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/website/pages/vagrant-cloud/api.mdx b/website/pages/vagrant-cloud/api.mdx
index f8afa0708..c0afdebf3 100644
--- a/website/pages/vagrant-cloud/api.mdx
+++ b/website/pages/vagrant-cloud/api.mdx
@@ -1510,4 +1510,87 @@ end
 }
 ```
 
+### Upload a provider directly to backend storage
+
+`GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload/direct`
+
+Prepares the provider for upload. This version of the upload API allows uploading the box asset directly to the backend storage. It requires
+a two step process for uploading the box assets. First uploading the asset to storage and then finalizing the upload within Vagrant Cloud
+via a provided callback.
+
+The request returns a JSON blob containing two fields:
+
+- `upload_path` - URL to `PUT` the box asset
+- `callback` - Vagrant Cloud callback URL to finalize upload
+
+The box asset is uploaded directly to the URL provided by the `upload_path` via a `PUT` request. Once complete, a `PUT` request to the URL
+provided in the `callback` field (complete with authentication header) finalizes the upload.
+
+~> The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL.
+
+#### Example Request
+
+<Tabs>
+<Tab heading="cURL">
+
+```shell
+response=$(curl \
+  --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \
+  https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload/direct)
+
+# Requires the jq command
+upload_path=$(echo "$response" | jq .upload_path)
+callback=$(echo "$response" | jq .callback)
+
+curl \
+  "$upload_path" \
+  --request PUT \
+  --upload-file virtualbox-1.2.3.box
+
+curl
+  $callback \
+  --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \
+  --request PUT
+```
+
+</Tab>
+<Tab heading="Ruby">
+
+```ruby
+# gem install http, or add `gem "http"` to your Gemfile
+require "http"
+require "uri"
+
+api = HTTP.persistent("https://app.vagrantup.com").headers(
+  "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}"
+)
+
+response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload")
+
+if response.status.success?
+  # Success, you can now upload the box image to the returned URL
+  upload_path = response.parse['upload_path']
+  callback = response.parse['callback']
+  # Upload the box asset
+  HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box")
+  # Finalize the upload
+  api.put(URI.parse(callback).path)
+else
+  # Error, inspect the `errors` key for more information.
+  p response.code, response.body
+end
+```
+
+</Tab>
+</Tabs>
+
+#### Example Response
+
+```json
+{
+  "upload_path": "https://remote-storage.example.com/bucket/630e42d9-2364-2412-4121-18266770468e?auth=9023wqfda",
+  "callback": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload/direct/630e42d9-2364-2412-4121-18266770468e"
+}
+```
+
 [markdown]: https://daringfireball.net/projects/markdown/syntax