From a2abbcdc92ba03b94cb5fefed3297d6c3b7359bc Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Thu, 12 Jul 2018 16:18:47 -0400 Subject: [PATCH 1/2] website: Document Vagrant Cloud search API --- .../source/docs/vagrant-cloud/api.html.md.erb | 95 +++++++++++++++++++ website/source/layouts/vagrant-cloud.erb | 3 + 2 files changed, 98 insertions(+) diff --git a/website/source/docs/vagrant-cloud/api.html.md.erb b/website/source/docs/vagrant-cloud/api.html.md.erb index 5b6d17ae1..5aa0f356e 100644 --- a/website/source/docs/vagrant-cloud/api.html.md.erb +++ b/website/source/docs/vagrant-cloud/api.html.md.erb @@ -530,6 +530,101 @@ Sends a 2FA code to the requested delivery method. } ``` +## Search + +### Search for boxes + +`GET /api/v1/search` + +#### Arguments + +* `q` - (Optional) The search query. Results will match the `username`, `name`, or `short_description` fields for a box. If omitted, the top boxes based on `sort` and `order` will be returned (defaults to "downloads desc"). +* `provider` - (Optional) Filter results to boxes supporting for a specific provider. +* `sort` - (Optional, default: `"downloads"`) The field to sort results on. Can be one of `"downloads"`, `"created"`, or `"updated"`. +* `order` - (Optional, default: `"desc"`) The order to return the sorted field in. Can be `"desc"` os `"asc"`. +* `limit` - (Optional, default: `10`) The number of results to return (max of 100). +* `page` - (Optional, default: `1`) + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/search?q=test&provider=virtualbox + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/search", params: { + q: "test", + 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 +{ + "boxes": [ + { + "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" + } + ] + } + } + ] +} +``` + ## Boxes ### Read a box diff --git a/website/source/layouts/vagrant-cloud.erb b/website/source/layouts/vagrant-cloud.erb index 8cf8f0d77..a43bfb916 100644 --- a/website/source/layouts/vagrant-cloud.erb +++ b/website/source/layouts/vagrant-cloud.erb @@ -87,6 +87,9 @@
  • Read an organization
    • +
  • + Search +
  • Boxes