# HTTP Resource

Turn any external HTTP API into a fully-featured Avo resource and manage remote data like it's local.

- Price: $40/month
- Gem: `gem "avo-http_resource"`
- Web page: https://avohq.io/addons/http-resource
- Pricing: https://avohq.io/pricing.md

Have any API available inside Avo in a few minutes. HTTP Resource backs an Avo resource with an external endpoint instead of Active Record, so a Stripe, GitHub, or in-house REST API shows up in your Avo app as a normal index, show, edit, and new screen, with no local table or model to set up first. You manage records that live behind an API the same way you manage your database tables.

Generate one with `bin/rails generate avo:resource Author --http`, point the `http_adapter` hash at the endpoint, map the JSON back to fields, and you have a working admin screen, no HTTParty client, pagination, or CRUD plumbing to generate and review. The slow part of putting a third-party API behind an admin is already built and vetted.

## What it looks like

One `http_adapter` block turns a REST endpoint into a full Avo resource:

```
class Avo::Resources::Author < Avo::BaseResource
  self.http_adapter = {
    endpoint: "https://api.example.com/authors",
    headers: { "Authorization" => "Bearer " + ENV["API_TOKEN"] },
    parse_collection: ->(response) { response.parsed_response["data"] },
    parse_record: ->(response) { response.parsed_response["author"] },
    parse_count: ->(response) { response.parsed_response["meta"]["total"] }
  }

  def fields
    field :id, as: :id
    field :name, as: :text
    field :email, as: :text
  end
end
```

## What you get

- Stand up a full admin for any REST API in one command, `bin/rails generate avo:resource Name --http`, with no table or model behind it
- Manage records that never touch your database: point `http_adapter` at the endpoint and the upstream API behaves like a normal Avo resource
- Render messy upstream payloads cleanly by reshaping JSON to your fields with `parse_collection`, `parse_record`, and `parse_count`
- Work against authenticated, paginated APIs out of the box, pass tokens through `headers` and build query strings from controller params
- Edit a remote record the way you edit a local one, with full create, read, update, and delete over HTTP through the built-in HTTParty client
- Fail gracefully when the upstream API is down: raise `Avo::HttpError` and the user sees a flash message instead of a stack trace

## Why it pays off

- Go from an API endpoint to a working admin in a few minutes, instead of building a client, pagination, and CRUD plumbing over a sprint.
- Every Avo release makes it better: the HTTParty client, request timeouts, and error handling stay maintained and keep working through upgrades, and fixes reach your app with bundle update.
- Your API-backed records reuse the same Avo resource, field, and action machinery, so they look and behave like the rest of your app, not a bolted-on one-off.

## Questions

### Can my team create and edit records through an HTTP Resource?

Yes. By default Avo sends a `POST` to the endpoint on create, a `PATCH` to `endpoint/:id` on update and a `DELETE` on destroy. If the API expects something else, override `save_record` and `destroy_record`.

### Does pagination work with an external API?

Avo sends `page` and `per_page` on every index request and reads the total from `parse_count`, or from `response["total"]` if you only set the endpoint. Sorting is yours to map onto the API's query string through `query_params`.