|
1 | | -# Foobara::EmptyRubyProjectGenerator |
| 1 | +# Foobara::HttpApiCommand |
2 | 2 |
|
3 | | -TODO: Delete this and the text below, and describe your gem |
| 3 | +`foobara-http-api-command` encapsulates external HTTP API calls in a Foobara command. |
4 | 4 |
|
5 | | -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library |
6 | | -into a gem. Put your Ruby code in the file `lib/foobara/empty_ruby_project_generator`. To experiment with that code, |
7 | | -run `bin/console` for an interactive prompt. |
| 5 | +It supports GET requests with query parameters and POST requests with JSON bodies, and parses successful JSON responses. |
8 | 6 |
|
9 | 7 | ## Installation |
10 | 8 |
|
11 | | -TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it |
12 | | -to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with |
13 | | -instructions to install your gem from git if you don't plan to release to RubyGems.org. |
| 9 | +Add `gem "foobara-http-api-command"` to your Gemfile or .gemspec file and `bundle install`. |
14 | 10 |
|
15 | | -Install the gem and add to the application's Gemfile by executing: |
| 11 | +Or even just `gem install foobara-http-api-command` if just playing with it directly in the scripts. |
16 | 12 |
|
17 | | - $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG |
| 13 | +## Usage |
18 | 14 |
|
19 | | -If bundler is not being used to manage dependencies, install the gem by executing: |
| 15 | +### Making a GET request |
20 | 16 |
|
21 | | - $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG |
| 17 | +Require the library and include `Foobara::HttpApiCommand` in a command class. |
22 | 18 |
|
23 | | -## Usage |
| 19 | +```ruby |
| 20 | +require "foobara/http_api_command" |
| 21 | + |
| 22 | +class Search < Foobara::Command |
| 23 | + include Foobara::HttpApiCommand |
| 24 | + |
| 25 | + inputs do |
| 26 | + query :string, :required |
| 27 | + end |
24 | 28 |
|
25 | | -TODO: Write usage instructions here |
| 29 | + result [Hash] |
26 | 30 |
|
27 | | -## Development |
| 31 | + base_url "https://rubygems.org/api/v1" |
| 32 | + path "/search.json" |
28 | 33 |
|
29 | | -If using Foobara locally, then run the following (TODO: make this no-longer necessary.) |
| 34 | + def build_request_body |
| 35 | + self.request_body = { query: } |
| 36 | + end |
| 37 | +end |
30 | 38 |
|
31 | | -```bash |
32 | | -bundle config set disable_local_branch_check true |
| 39 | +results = Search.run!(query: "foobara") |
| 40 | +pp results.first # => an Array of Hash results from the API |
33 | 41 | ``` |
34 | 42 |
|
35 | | -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can |
36 | | -also run `bin/console` for an interactive prompt that will allow you to experiment. |
| 43 | +### Making a POST request |
| 44 | + |
| 45 | +To make a POST request, set `http_method :post`. The request body will then be sent as JSON. |
| 46 | + |
| 47 | +```ruby |
| 48 | +require "foobara/http_api_command" |
| 49 | + |
| 50 | +class PostExample < Foobara::Command |
| 51 | + include Foobara::HttpApiCommand |
37 | 52 |
|
38 | | -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the |
39 | | -version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, |
40 | | -push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). |
| 53 | + inputs do |
| 54 | + foo :string, :required |
| 55 | + end |
| 56 | + |
| 57 | + result Hash |
| 58 | + url "https://httpbin.org/post" |
| 59 | + http_method :post |
| 60 | + http_timeout 120 |
| 61 | + |
| 62 | + def build_request_body |
| 63 | + self.request_body = { foo: } |
| 64 | + end |
| 65 | +end |
| 66 | + |
| 67 | +response = PostExample.run!(foo: "bar") |
| 68 | +pp response.fetch("json") # => {"foo"=>"bar"} |
| 69 | +``` |
41 | 70 |
|
42 | 71 | ## Contributing |
43 | 72 |
|
44 | | -Bug reports and pull requests are welcome on GitHub |
45 | | -at https://github.com/[USERNAME]/foobara-empty_ruby_project_generator. |
| 73 | +Bug reports and pull requests are welcome at [foobara/http-api-command](https://github.com/foobara/http-api-command). |
| 74 | + |
| 75 | +To work on an existing issue or submit a PR: |
| 76 | + |
| 77 | +1. Fork the repository and clone it to your local machine |
| 78 | +2. Run `bundle install` to install dependencies |
| 79 | +3. Run `rake` to ensure that everything works as expected before making any changes |
| 80 | +4. Implement your changes |
| 81 | +5. Re-run `rake` to make sure that all tests and Rubocop pass |
| 82 | +6. Commit your changes, push to GitHub and open a Pull Request for review |
46 | 83 |
|
47 | 84 | ## License |
48 | 85 |
|
49 | | -This files in this project are licensed under the |
50 | | -Mozilla Public License Version 2.0. Please see LICENSE.txt for more info. |
| 86 | +This project is licensed under the MPL-2.0 license. Please see [LICENSE.txt](LICENSE.txt) for more information. |
0 commit comments