heroku/heroku-api-plugin

Heroku API plugin for Heroku Toolbelt

API Plugin for Heroku Toolbelt

How to install this plugin

$ heroku plugins:install @heroku-cli/plugin-api

Usage

• heroku api METHOD [PATH]

heroku api METHOD [PATH]

make a manual API request

USAGE
  $ heroku api METHOD [PATH]

ARGUMENTS
  METHOD  GET, POST, PUT, PATCH, or DELETE
  PATH    endpoint to call

OPTIONS
  -a, --accept-inclusion=accept-inclusion  Accept-Inclusion header to use
  -b, --body=body                          JSON input body
  -v, --version=version                    version to use (e.g. 2, 3, or 3.variant)

DESCRIPTION
  The api command is a convenient but low-level way to send requests
  to the Heroku API. It sends an HTTP request to the Heroku API
  using the given method on the given path. For methods PUT, PATCH,
  and POST, it uses stdin unmodified as the request body. It prints
  the response unmodified on stdout.

  It is essentially like curl for the Heroku API.

  Method name input will be upcased, so both 'heroku api GET /apps' and
  'heroku api get /apps' are valid commands.

EXAMPLE
  $ heroku api GET /apps/myapp
  {
     created_at: "2011-11-11T04:17:13-00:00",
     id: "12345678-9abc-def0-1234-456789012345",
     name: "myapp",
     …
  }

  $ heroku api PATCH /apps/myapp/config-vars --body '{"FOO": "bar"}'
  {
     FOO: "bar"
     …
  }

  $ export HEROKU_HEADERS
  $ HEROKU_HEADERS='{
  "Content-Type": "application/x-www-form-urlencoded",
  "Accept": "application/json"
  }'
  $ printf 'type=web&qty=2' | heroku api POST /apps/myapp/ps/scale
  2

See code: src/commands/api.ts

heroku-api-plugin's Issues

add heroku user to plugin

just in case someone needs to push a patch, it would be good to add the shared heroku account as a collab: https://www.npmjs.com/~heroku

more explicit user agent

Doesn't look like one is being set, which probably means it falls back to default node one.

Cut a release

The comment for HEROKU_HEADERS indicates it should be a json hash on this repo, but not on the currently released version which is from 2018 https://github.com/heroku/heroku-api-plugin/releases/tag/v2.1.10

---

As a side note, I couldn't get it to work even using the code on master and manually linking:

$ export HEROKU_HEADERS='{
  "Content-Type": "appplication/json",
  "Accept": "application/vnd.heroku+json; version=3.dyno-release"
}'

$ heroku api POST /apps/stormy-scrubland-58269/dynos --body='{"command": "ls"}'
POST api.heroku.com/apps/stormy-scrubland-58269/dynos... !
TypeError [ERR_INVALID_ARG_TYPE] [ERR_INVALID_ARG_TYPE]: The "string" argument must be of type string or an instance of Buffer or ArrayBuffer. Received an instance of Object
    at APIHTTPClient._parseBody (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/http-call/lib/http.js:313:57)
    at new HTTP (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/http-call/lib/http.js:65:18)
    at new CustomHTTP (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/http-call/lib/http.js:69:21)
    at new APIHTTPClient (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/@heroku-cli/command/lib/api_client.js:49:21)
    at Function.request (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/http-call/lib/http.js:161:20)
    at Function.request (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/@heroku-cli/command/lib/api_client.js:74:40)
    at APIClient.request (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/node_modules/@heroku-cli/command/lib/api_client.js:156:26)
    at fetch (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/src/commands/api.ts:95:38)
    at API.run (~/Documents/projects/plugins-for-heroku/heroku-api-plugin/src/commands/api.ts:110:22)

show CURL command

add a flag or something to output how to run a curl command to hit the same endpoint

Accept the endpoint without starting with /

It happens to me from now and then, so I figure I dropped this feedback in case I'm not the only one:

Sometimes, I do this and surprised by the error message:

› h api get apps
undefined:1
400 Bad Request
    ^

SyntaxError: Unexpected token B in JSON at position 4
    at JSON.parse (<anonymous>)
    at Request.parseBody (/Users/rbarroso/.local/share/heroku/plugins/node_modules/heroku-api-plugin/node_modules/heroku-client/lib/request.js:256:17)
    at Request.handleFailure (/Users/rbarroso/.local/share/heroku/plugins/node_modules/heroku-api-plugin/node_modules/heroku-client/lib/request.js:286:19)
    at /Users/rbarroso/.local/share/heroku/plugins/node_modules/heroku-api-plugin/node_modules/heroku-client/lib/request.js:163:14
    at IncomingMessage.<anonymous> (/Users/rbarroso/.local/share/heroku/plugins/node_modules/heroku-api-plugin/node_modules/heroku-client/lib/request.js:392:5)
    at emitNone (events.js:91:20)
    at IncomingMessage.emit (events.js:188:7)
    at endReadableNT (_stream_readable.js:975:12)
    at _combinedTickCallback (internal/process/next_tick.js:80:11)
    at process._tickCallback (internal/process/next_tick.js:104:9)

Then I realize that I forgot including the / at the beginning.

› h api get /apps
... # my apps

I think it'd be nice to make it work without the first /.

Installation instructions are broken

If I follow the install instructions in the README, I get an api package installed that is not a Heroku CLI plugin, and could potentially be a security risk:

$ heroku plugins:install api
Installing plugin api... ⢿ [1/4] Resolving packages...
Installing plugin api... ⣾ [3/4] Linking dependencies...
Installing plugin api... installed v6.1.1

$ heroku api --help
(node:18217) Error Plugin: api: files attribute must be specified in /Users/emorley/.local/share/heroku/node_modules/api/package.json
module: @oclif/[email protected]
plugin: api
root: /Users/emorley/.local/share/heroku/node_modules/api
See more details with DEBUG=*
(Use `node --trace-warnings ...` to show where the warning was created)
 ›   Error: Command api not found.

I presume this is because the Heroku CLI no longer magically resolves plugin names to their long form (which is likely a good thing; that magic was never a good idea IMO), and so instead the install instructions need to say to run:

heroku plugins:install @heroku-cli/plugin-api

unmet peer dependency warning when installing plugin

Installing the plugin I get an unmet peer dependency warning:

h plugins:install api
warning "@heroku-cli/plugin-api > @oclif/[email protected]" has unmet peer dependency "@oclif/plugin-help@^2".
...

Since:
https://github.com/oclif/command/blob/v1.5.16/package.json#L32-L35

(The plugin functions fine once installed however)

Support --json to output in JSON instead of JavaScript

It'd be nice to be able to pipe the output to |jq or similar.

lib/errors.js is trying to write to ~/.cache/heroku/error.log

2FA prompt is not visible

If I hit an endpoint that requires 2FA, the CLI does prompt me, but the prompt is hidden:

maciek@mothra:~$ h api get /addons/postgresql-fitted-99834/addon-attachments
GET api.heroku.com/addons/postgresql-fitted-99834/addon-attachments... ⣷

At this point, the "waiting" spinner keeps spinning indefinitely. If I press my Yubikey, the 2FA code is passed along to the API and the call completes, but it's not at all clear that this is what I have to do.