{"id":13880006,"url":"https://github.com/interagent/heroics","last_synced_at":"2025-04-05T17:09:03.632Z","repository":{"id":47482377,"uuid":"11801614","full_name":"interagent/heroics","owner":"interagent","description":"Ruby HTTP client for APIs represented with JSON schema","archived":false,"fork":false,"pushed_at":"2024-06-21T14:45:24.000Z","size":296,"stargazers_count":413,"open_issues_count":8,"forks_count":34,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-03-29T16:08:09.249Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interagent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-31T21:21:19.000Z","updated_at":"2024-10-18T15:55:34.000Z","dependencies_parsed_at":"2022-09-18T04:41:25.022Z","dependency_job_id":null,"html_url":"https://github.com/interagent/heroics","commit_stats":null,"previous_names":["heroku/heroics"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fheroics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fheroics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fheroics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interagent%2Fheroics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interagent","download_url":"https://codeload.github.com/interagent/heroics/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:02:43.172Z","updated_at":"2025-04-05T17:09:03.601Z","avatar_url":"https://github.com/interagent.png","language":"Ruby","readme":"[![Build Status](https://travis-ci.org/interagent/heroics.png?branch=master)](https://travis-ci.org/interagent/heroics)\n# Heroics\n\nRuby HTTP client generator for APIs represented with JSON schema.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'heroics'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install heroics\n\n## Usage\n\n### Configuration File\n\nIf you don't want to pass config to the CLI, you can provide a Ruby config file to the `heroics-generate` script as a single parameter.\n\nThe form of this configuration file is shown below.\n\n```ruby\nrequire 'heroics'\n\nHeroics.default_configuration do |config|\n  config.base_url = 'https://example.com'\n  config.module_name = 'ExampleClient'\n  config.schema_filepath = 'schema.json'\n\n  config.headers = { 'Accept' =\u003e 'application/vnd.example+json; version=1' }\n\n  # Note: Don't use doublequotes below -- we want to interpolate at runtime,\n  # not when the client is generated\n  config.cache_path = '#{Dir.home}/.heroics/example'\nend\n```\n\n#### Optional configuration\n\n`base_url`, `module_name`, and `schema_filepath` are required for a proper configuration.\n\nThe following keys are optional:\n\n* `headers`\n* `cache_path`\n* `ruby_name_replacements` a hash of replacement patterns for converting endpoint paths to Ruby method names, such as:\n\u003e { /[\\s-]+/ =\u003e '_' }\n\nFor further details on config file usage, see the `example/` directory in this repo.\n\n### Generating a client\n\nHeroics generates an HTTP client from a JSON schema that describes your API.\nLook at [prmd](https://github.com/interagent/prmd) for tooling to help write a\nJSON schema.  When you have a JSON schema prepared you can generate a client\nfor your API:\n\n```\nheroics-generate MyApp schema.json https://api.myapp.com \u003e client.rb\n```\n\nIf you are using a configuration file, per above, just pass the path to it:\n\n```\nheroics-generate my-config-file.rb \u003e client.rb\n```\n\n### Passing custom headers\n\nIf your client needs to pass custom headers with each request these can be\nspecified using `-H`:\n\n```\nheroics-generate \\\n  -H \"Accept: application/vnd.myapp+json; version=3\" \\\n  MyApp \\\n  schema.json \\\n  https://api.myapp.com \u003e client.rb\n```\n\nPass multiple `-H` options if you need more than one custom header.\n\n### Client-side caching\n\nThe generated client sends and caches ETags received from the server.  By\ndefault, this data is cached in memory and is only used during the lifetime of\na single instance.  You can specify a directory for cache data:\n\n```\nheroics-generate \\\n  -c \"~/.heroics/myapp\" \\\n  MyApp \\\n  schema.json \\\n  https://api.myapp.com \u003e client.rb\n```\n\n`~` will automatically be expanded to the user's home directory.  Be sure to\nwrap such paths in quotes to avoid the shell expanding it to the directory you\nbuilt the client in.\n\n### Generating API documentation\n\nThe generated client has [Yard](http://yardoc.org/)-compatible docstrings.\nYou can generate documentation using `yardoc`:\n\n```\nyard doc -m markdown client.rb\n```\n\nThis will generate HTML in the `docs` directory.  Note that Yard creates an\n`_index.html` page won't be served by Jekyll on GitHub Pages.  Add a\n`.nojekyll` file to your project to prevent GitHub from passing the content\nthrough Jekyll.\n\n### Handling failures\n\nThe client uses [Excon](https://github.com/geemus/excon) under the hood and\nraises Excon errors when failures occur.\n\n```ruby\nbegin\n  client.app.create({'name' =\u003e 'example'})\nrescue Excon::Errors::Forbidden =\u003e error\n  puts error\nend\n```\n\n## Contributing\n\n1. [Fork the repository](https://github.com/interagent/heroics/fork)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new pull request\n","funding_links":[],"categories":["API Client Development Tools","Ruby"],"sub_categories":["Ruby"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteragent%2Fheroics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finteragent%2Fheroics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteragent%2Fheroics/lists"}