From 9c00219903e34839cc738c34739b6eefb7a0901f Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Wed, 18 Oct 2017 17:20:29 -0400 Subject: [PATCH] website: Vagrant Cloud API docs --- website/source/docs/vagrant-cloud/api.html.md | 1238 +++++++++++++++++ website/source/layouts/docs.erb | 61 +- 2 files changed, 1298 insertions(+), 1 deletion(-) create mode 100644 website/source/docs/vagrant-cloud/api.html.md diff --git a/website/source/docs/vagrant-cloud/api.html.md b/website/source/docs/vagrant-cloud/api.html.md new file mode 100644 index 000000000..b7afc587a --- /dev/null +++ b/website/source/docs/vagrant-cloud/api.html.md @@ -0,0 +1,1238 @@ +--- +layout: "docs" +page_title: "Vagrant Cloud API" +sidebar_current: "vagrant-cloud-api" +--- + +# Vagrant Cloud API + +* [Using the API](#using-the-api) + * [Authentication](#authentication) + * [Request and Response Format](#request-and-response-format) + * [Response Codes](#response-codes) +* [Creating a usable box from scratch](#creating-a-usable-box-from-scratch) +* [Authentication Tokens](#authentication-tokens) + * [Create a token](#create-a-token) + * [Validate a token](#validate-a-token) +* [Boxes](#boxes) + * [Read a box](#read-a-box) + * [Create a box](#create-a-box) + * [Update a box](#update-a-box) + * [Delete a box](#delete-a-box) +* [Versions](#versions) + * [Read a version](#read-a-version) + * [Create a version](#create-a-version) + * [Update a version](#update-a-version) + * [Delete a version](#delete-a-version) + * [Release a version](#release-a-version) + * [Revoke a version](#revoke-a-version) +* [Providers](#providers) + * [Read a provider](#read-a-provider) + * [Create a providers](#create-a-provider) + * [Update a provider](#update-a-provider) + * [Delete a provider](#delete-a-provider) + * [Upload a provider](#upload-a-provider) + + +## Using the API + +Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application. + +### Authentication + +Some API endpoints require authentication to create new resources, update or delete existing resources, or to read a private resource. + +Clients can authenticate using an authentication token. +The token can be passed to Vagrant Cloud one of two ways: + +1. (Preferred) Set the `X-Atlas-Token` header to the value of the authentication token. +2. Pass the authentication token as an `access_token` URL parameter. + +Examples below will set the header, but feel free to use whichever method is easier for your implementation. + +-> The header name `X-Atlas-Token` is an artifact of Vagrant Cloud's previous project name, "Atlas". +-> This header will be updated in the near future, but `X-Atlas-Token` will continue to be supported for now to ensure backwards-compatibility. + +### Request and Response Format + +Requests to Vagrant Cloud which include data attributes (`POST` or `PUT`/`PATCH`) should set the `Content-Type` header to `"application/json"`, and include a valid JSON body with the request. + +JSON responses may include an `errors` key, which will contain an array of error strings, as well as a `success` key. +For example: + +```json +{ + "errors": [ + "Resource not found!" + ], + "success": false +} +``` + +### Response Codes + +Vagrant Cloud may response with the following response codes, depending on the status of the request and context: + +#### Success + +##### **200** OK +##### **201** Created + +#### Client Errors + +##### **401** Unauthorized + +You do not have authorization to access the requested resource. + +##### **402** Payment Required + +You are trying to access a resource which is delinquent on billing. +Please contact the owner of the resource so that they can update their billing information. + +##### **403** Forbidden + +You are attempting to use the system in a way which is not allowed. +There could be required request parameters that are missing, or one of the parameters is invalid. +Please check the response `errors` key, and double-check the examples below for any discrepancies. + +##### **404** Not Found + +The resource you are trying to access does not exist. This may also be returned if you attempt to access a private resource that you don't have authorization to view. + +##### **422** Unprocessable Entity + +##### **429** Too Many Requests + +You are currently being rate-limited. Please decrease your frequency of usage, or contact us at [support+vagrantcloud@hashicorp.com](mailto:support+vagrantcloud@hashicorp.com) with a description of your use case so that we can consider creating an exception. + +#### Server Errors + +##### **500** Internal Server Error + +The server failed to respond to the request for an unknown reason. +Please contact [support+vagrantcloud@hashicorp.com](mailto:support+vagrantcloud@hashicorp.com) with a description of the problem so that we can investigate. + +##### **503** Service Unavailable + +Vagrant Cloud is temporarily in maintenance mode. +Please check the [HashiCorp Status Site](http://status.hashicorp.com) for more information. + +## Creating a usable box from scratch + +-> This assumes that you have a valid Vagrant Cloud authentication token. You can [create one via the API](#create-a-token), or [create one on the Vagrant Cloud website](https://app.vagrantup.com/settings/security). + +In order to create a usable box on Vagrant Cloud, perform the following steps: + +1. [Create a new box](#create-a-box) +1. [Create a new version](#create-a-version) +1. [Create a new provider](#create-a-provider) +1. [Upload a box image for that provider](#upload-a-provider) +1. [Release the version](#release-a-version) + +#### Example Requests + +
+ +
+ ```shell + # Create a new box + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/boxes \ + --data '{ "box": { "username": "myuser", "name": "test" } }' + + # Create a new version + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/versions \ + --data '{ "version": { "version": "1.2.3" } }' + + # Create a new provider + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ + --data '{ "provider": { "name": "virtualbox" } }' + + # Prepare the provider for upload/get an upload URL + response=$(curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload) + + # Extract the upload URL from the response (requires the jq command) + upload_path=$(echo "$response" | jq .upload_path) + + # Perform the upload + curl $upload_path --request PUT --upload-file virtualbox-1.2.3.box + + # Release the version + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release \ + --request PUT + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + # Create a new box + api.post "/api/v1/boxes", + json: { box: { username: "myuser", name: "test" } } + + # Create a new version + api.post "/api/v1/box/myuser/test/versions", + json: { version: { version: "1.2.3" } } + + # Create a new provider + api.post "/api/v1/box/myuser/test/version/1.2.3/providers", + json: { provider: { name: "virtualbox" } } + + # Prepare the provider for upload + response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + + # Extract the upload URL + upload_path = response.parse['upload_path'] + + # Upload the box image + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") + ``` +
+
+ +## Authentication Tokens + +### Create a token + +`POST /api/v1/authenticate` + +Creates a new token for the given user. + +#### Arguments + +* `token` + * `desription` (Optional) - A description of the token. +* `user` + * `login` - Username or email address of the user authenticating. + * `password` - The user's password. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + https://app.vagrantup.com/api/v1/authenticate \ + --data ' + { + "token": { + "description": "Login from cURL" + }, + "user": { + "login": "myuser", + "password": "secretpassword" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json" + ) + + response = api.post("/api/v1/authenticate", json: { + token: { description: "Login from Ruby" }, + user: { login: "myuser", password: "secretpassword" } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "description": "Login from cURL", + "token": "qwlIE1qBVUafsg.atlasv1.FLwfJSSYkl49i4qZIu8R31GBnI9r8DrW4IQKMppkGq5rD264lRksTqaIN0zY9Bmy0zs", + "token_hash": "7598236a879ecb42cb0f25399d6f25d1d2cfbbc6333392131bbdfba325eb352795c169daa4a61a8094d44afe817a857e0e5fc7dc72a1401eb434577337d1246c", + "created_at": "2017-10-18T19:16:24.956Z" +} +``` + +### Validate a token + +`GET /api/v1/authenticate` + +Responds [`200 OK`](#200-ok) if the authentication request was successful, otherwise responds [`401 Unauthorized`](#401-unauthorized). + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/authenticate + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.get("/api/v1/authenticate") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +## Boxes + +### Read a box + +`GET /api/v1/box/:username/:name` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.get("/api/v1/box/myuser/test") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + }, + "versions": [ + { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + ] +} +``` + +### Create a box + +`POST /api/v1/boxes` + +#### Arguments + +* `box` + * `username` - The username of the organization that will own this box. + * `name` - The name of the box. + * `short_description` - A short summary of the box. + * `description` - A longer description of the box. Can be formatted with [Markdown][markdown]. + * `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/boxes \ + --data ' + { + "box": { + "username": "myuser", + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.post("/api/v1/boxes", json: { + box: { + username: "myuser", + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +### Update a box + +`PUT /api/v1/box/:username/:name` + +#### Arguments + +* `box` + * `name` - The name of the box. + * `short_description` - A short summary of the box. + * `description` - A longer description of the box. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + * `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test \ + --request PUT \ + --data ' + { + "box": { + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' + ``` + + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.put("/api/v1/box/myuser/test", json: { + box: { + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +### Delete a box + +`DELETE /api/v1/box/:username/:name` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/box/myuser/test + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.delete("/api/v1/box/myuser/test") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +## Versions + +### Read a version + +`GET /api/v1/box/:username/:name/version/:version` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.get("/api/v1/box/myuser/test/version/1.2.3") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] +} +``` + +### Create a version + +`POST /api/v1/box/:username/:name/versions` + +-> New versions start as `unreleased`. You must create a valid provider before releasing a new version. + +#### Arguments + +* `version` + * `versions` - The version number of this version. + * `description` - A description for this version. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/versions \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.post("/api/v1/box/myuser/test/versions", json: { + version: { + version: "1.2.3", + description: "A new version" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Update a version + +`PUT /api/v1/box/:username/:name/version/1.2.3` + +#### Arguments + +* `version` + * `versions` - The version number of this version. + * `description` - A description for this version. Can be formatted with [Markdown][markdown]. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 \ + --request PUT \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3", json: { + version: { + name: "1.2.3", + description: "A new version" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Delete a version + +`DELETE /api/v1/box/:username/:name/version/:version` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.delete("/api/v1/box/myuser/test/version/1.2.3") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Release a version + +`PUT /api/v1/box/:username/:name/version/1.2.3/release` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release \ + --request PUT + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3/release") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Revoke a version + +`PUT /api/v1/box/:username/:name/version/1.2.3/revoke` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke \ + --request PUT + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3/revoke") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +## Providers + +### Read a provider + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ + +#### Example Response + +```json +{ + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" +} +``` + +### Create a provider + +`POST /api/v1/box/:username/:name/version/:version/providers` + +#### Arguments + +* `provider` + * `name` - The name of the provider. + * `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ + --data ' + { + "provider": { + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.post("/api/v1/box/myuser/test/version/1.2.3/providers", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Update a provider + +`PUT /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Arguments + +* `provider` + * `name` - The name of the provider. + * `url` - A valid URL to download this provider. If omitted, you must [upload](#TODO) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/virtualbox \ + --request PUT \ + --data ' + { + "provider": { + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3/virtualbox", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Delete a provider + +`DELETE /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.delete("/api/v1/box/myuser/test/verison/1.2.3/provider/virtualbox") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Upload a provider + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload` + +Prepares the provider for upload, and returns a JSON blob containing an `upload_path`. + +~> 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 + +
+ +
+ ```shell + response=$(curl \ + --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/virtualbox/upload) + + # Requires the jq command + upload_path=$(echo "$response" | jq .upload_path) + + curl \ + $upload_path \ + --request PUT \ + --upload-file virtualbox-1.2.3.box + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN'] + ) + + response = api.get("/api/v1/box/myuser/test/version/1.2.3/virtualbox/upload") + + if response.status.success? + # Success, you can now upload the box image to the returned URL + upload_path = response.parse['upload_path'] + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e" +} +``` + +[markdown]: https://daringfireball.net/projects/markdown/syntax diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 47f014f59..b4f35125c 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -1,3 +1,61 @@ +<% content_for :head do %> + + + +<% end %> + <% wrap_layout :inner do %> <% content_for :sidebar do %>