{"id":13463455,"url":"https://github.com/codegram/hyperclient","last_synced_at":"2025-03-25T06:32:05.005Z","repository":{"id":2872116,"uuid":"3877860","full_name":"codegram/hyperclient","owner":"codegram","description":"HyperClient is a Ruby Hypermedia API client.","archived":false,"fork":false,"pushed_at":"2024-05-24T02:11:17.000Z","size":710,"stargazers_count":153,"open_issues_count":17,"forks_count":35,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-18T19:52:52.196Z","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/codegram.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-03-30T15:20:11.000Z","updated_at":"2024-08-26T21:28:10.000Z","dependencies_parsed_at":"2024-05-12T17:41:14.679Z","dependency_job_id":"6f4946f0-5eef-4468-b1a3-f1d36163a4ad","html_url":"https://github.com/codegram/hyperclient","commit_stats":{"total_commits":343,"total_committers":27,"mean_commits":"12.703703703703704","dds":0.5830903790087463,"last_synced_commit":"e446423677da1925bd89d43230b3f242c44fc2d9"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegram%2Fhyperclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegram%2Fhyperclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegram%2Fhyperclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codegram%2Fhyperclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codegram","download_url":"https://codeload.github.com/codegram/hyperclient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245414390,"owners_count":20611359,"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-07-31T13:00:53.781Z","updated_at":"2025-03-25T06:32:04.722Z","avatar_url":"https://github.com/codegram.png","language":"Ruby","readme":"# Hyperclient\n\n[![Gem Version](http://img.shields.io/gem/v/hyperclient.svg)](http://badge.fury.io/rb/hyperclient)\n[![Build Status](https://github.com/codegram/hyperclient/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/codegram/hyperclient/actions/workflows/test.yml)\n[![Code Climate](https://codeclimate.com/github/codegram/hyperclient.svg)](https://codeclimate.com/github/codegram/hyperclient)\n[![Coverage Status](https://img.shields.io/coveralls/codegram/hyperclient.svg)](https://coveralls.io/r/codegram/hyperclient?branch=master)\n\nHyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON HAL](http://stateless.co/hal_specification.html).\n\n# Table of Contents\n\n- [Usage](#usage)\n  - [API Client](#api-client)\n  - [Resources and Attributes](#resources-and-attributes)\n  - [Links and Embedded Resources](#links-and-embedded-resources)\n  - [Templated Links](#templated-links)\n  - [Curies](#curies)\n  - [Attributes](#attributes)\n  - [HTTP](#http)\n- [Testing Using Hyperclient](#testing-using-hyperclient)\n- [Reference](#reference)\n- [Hyperclient Users](#hyperclient-users)\n- [Contributing](#contributing)\n- [License](#license)\n\n# Usage\n\nThe examples in this README use the [Splines Demo API](https://github.com/ruby-grape/grape-with-roar) running [here](https://grape-with-roar.herokuapp.com/api). Use version 1.x with Faraday 1.x, and version 2.x with Faraday 2.x. If you're upgrading from a previous version, please make sure to read [UPGRADING](UPGRADING.md).\n\n## API Client\n\nCreate an API client.\n\n```ruby\nrequire 'hyperclient'\n\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')\n```\n\nBy default, Hyperclient adds `application/hal+json` as `Content-Type` and `Accept` headers. It will also send requests as JSON and parse JSON responses. Specify additional headers or authentication if necessary.\n\n```ruby\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|\n  client.headers['Access-Token'] = 'token'\nend\n```\n\nHyperclient constructs a connection using typical [Faraday](http://github.com/lostisland/faraday) middleware for handling JSON requests and responses. You can specify additional Faraday middleware if necessary.\n\n```ruby\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|\n  client.connection do |conn|\n    conn.use Faraday::Request::Instrumentation\n  end\nend\n```\n\nYou can pass options to the Faraday connection block in the `connection` block:\n\n```ruby\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|\n  client.connection(ssl: { verify: false }) do |conn|\n    conn.use Faraday::Request::Instrumentation\n  end\nend\n```\n\nOr when using the default connection configuration you can use `faraday_options`:\n\n```ruby\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|\n  client.faraday_options = { ssl: { verify: false } }\nend\n```\n\nYou can build a new Faraday connection block without inheriting default middleware by specifying `default: false` in the `connection` block.\n\n```ruby\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|\n  client.connection(default: false) do |conn|\n    conn.request :json\n    conn.response :json, content_type: /\\bjson$/\n    conn.adapter :net_http\n  end\nend\n```\n\nYou can modify headers or specify authentication after a connection has been created. Hyperclient supports Basic, Token or [Digest auth](https://github.com/bhaberer/faraday-digestauth) as well as many other Faraday extensions.\n\n```ruby\nrequire 'faraday/digestauth'\n\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|\n  client.connection(default: false) do |conn|\n    conn.request :digest, 'username', 'password'\n    conn.request :json\n    conn.response :json, content_type: /\\bjson$/\n    conn.adapter :net_http\n  end\nend\n```\n\nYou can access the Faraday connection directly after it has been created and add middleware to it. As an example, you could use the [faraday-http-cache-middleware](https://github.com/plataformatec/faraday-http-cache).\n\n```ruby\napi = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')\napi.connection.use :http_cache\n```\n\n## Resources and Attributes\n\nHyperclient will fetch and discover the resources from your API and automatically paginate when possible.\n\n```ruby\napi.splines.each do |spline|\n  puts \"A spline with ID #{spline.uuid}.\"\nend\n```\n\nOther methods, including `[]` and `fetch` are also available\n\n```ruby\napi.splines.each do |spline|\n  puts \"A spline with ID #{spline[:uuid]}.\"\n  puts \"Maybe with reticulated: #{spline.fetch(:reticulated, '-- no reticulated')}\"\nend\n```\n\n## Links and Embedded Resources\n\nThe splines example above followed a link called \"splines\". While you can, you do not need to specify the HAL navigational structure, including links or embedded resources. Hyperclient will resolve these for you.  If you prefer, you can explicitly navigate the link structure via `_links`. In the following example the \"splines\" link leads to a collection of embedded splines. Invoking `api.splines` is equivalent to `api._links.splines._embedded.splines`.\n\n```ruby\napi._links.splines\n```\n\n## Templated Links\n\nTemplated links require variables to be expanded. For example, the demo API has a link called \"spline\" that requires a spline \"uuid\".\n\n```ruby\nspline = api.spline(uuid: 'uuid')\nputs \"Spline #{spline.uuid} is #{spline.reticulated ? 'reticulated' : 'not reticulated'}.\"\n```\n\nInvoking `api.spline(uuid: 'uuid').reticulated` is equivalent to `api._links.spline._expand(uuid: 'uuid')._resource._attributes.reticulated`.\n\nThe client is responsible for supplying all the necessary parameters. Templated links don't do any strict parameter name checking and don't support required vs. optional parameters. Parameters not declared by the API will be dropped and will not have any effect when passed to `_expand`.\n\n## Curies\n\nCuries are a suggested means by which to link documentation of a given resource. For example, the demo API contains very long links to images that use an \"images\" curie.\n\n```ruby\nputs spline['image:thumbnail'] # =\u003e https://grape-with-roar.herokuapp.com/api/splines/uuid/images/thumbnail.jpg\nputs spline.links._curies['image'].expand('thumbnail') # =\u003e /docs/images/thumbnail\n```\n\n## Attributes\n\nResource attributes can also be accessed as a hash.\n\n```ruby\nputs spline.to_h # =\u003e {\"uuid\" =\u003e \"uuid\", \"reticulated\" =\u003e true}\n```\n\nThe above is equivalent to `spline._attributes.to_h`.\n\n## HTTP\n\nHyperclient uses [Faraday](http://github.com/lostisland/faraday) under the hood to perform HTTP calls. You can call any valid HTTP method on any resource.\n\nFor example, you can examine the API raw JSON by invoking `_get` and examining the `_response.body` hash.\n\n```ruby\napi._get\napi._response.body\n```\n\nOther methods, including `_head` or `_options` are also available.\n\n```ruby\nspline = api.spline(uuid: 'uuid')\nspline._head\nspline._options\n```\n\nInvoke `_post` to create resources.\n\n```ruby\nsplines = api.splines\nsplines._post(uuid: 'new uuid', reticulated: false)\n```\n\nInvoke `_put` or `_patch` to update resources.\n\n```ruby\nspline = api.spline(uuid: 'uuid')\nspline._put(reticulated: true)\nspline._patch(reticulated: true)\n```\n\nInvoke `_delete` to destroy a resource.\n\n```\nspline = api.spline(uuid: 'uuid')\nspline._delete\n```\n\nHTTP methods always return a new instance of Resource.\n\n# Testing Using Hyperclient\n\nYou can combine RSpec, Faraday::Adapter::Rack and Hyperclient to test your HAL API without having to ever examine the raw JSON response.\n\n```ruby\ndescribe Acme::Api do\n  def app\n    Acme::App.instance\n  end\n\n  let(:client) do\n    Hyperclient.new('http://example.org/api') do |client|\n      client.headers['Content-Type'] = 'application/json'\n      client.connection(default: false) do |conn|\n        conn.request :json\n        conn.response :json\n        conn.use Faraday::Adapter::Rack, app\n      end\n    end\n  end\n\n  it 'splines returns 3 splines by default' do\n    expect(client.splines.count).to eq 3\n  end\nend\n```\n\nFor a complete example refer to [this Splines Demo API test](https://github.com/ruby-grape/grape-with-roar/blob/master/spec/api/splines_endpoint_with_hyperclient_spec.rb).\n\n# Reference\n\n[Hyperclient API Reference](http://rubydoc.org/github/codegram/hyperclient/master/frames).\n\n# Hyperclient Users\n\nUsing Hyperclient? Add your project to our wiki, please: \u003chttps://github.com/codegram/hyperclient/wiki\u003e.\n\n# Contributing\n\nHyperclient is work of [many people](https://github.com/codegram/hyperclient/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/codegram/hyperclient/pulls), [propose features and discuss issues](https://github.com/codegram/hyperclient/issues). See [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n# License\n\nMIT License, see [LICENSE](LICENSE) for details.\n\nCopyright (c) 2012-2018 Oriol Gual, [Codegram Technologies](http://codegram.com) and Contributors\n","funding_links":[],"categories":["Web Apps, Services \u0026 Interaction"],"sub_categories":["HTTP clients"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodegram%2Fhyperclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodegram%2Fhyperclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodegram%2Fhyperclient/lists"}