graphiti 2.0.0.beta.6 → 2.0.0.beta.8

data/docs/getting-started/first-api.md

@@ -1,289 +0,0 @@
----
-title: 'Build Your First API'
----
-
-# Build Your First API
-
-By the end of this page you'll have a working Rails API, backed by Graphiti, that supports filtering, sorting, pagination, and nested relationships out of the box.
-
-We'll use Rails and ActiveRecord here, on familiar ground. For how the pieces fit together, see [Lifecycle of a Request](/concepts/overview).
-
-You'll need Ruby 3.2+ and Rails 7.1+ installed for this walkthrough. Graphiti itself only requires Ruby 3.2+ and ActiveSupport, so you can [use it without Rails](/getting-started/installation#without-rails).
-
-## Installation {#installation}
-
-Let's start with a classic Rails blog. We'll use a [template](http://guides.rubyonrails.org/rails_application_templates.html) to handle some of the boilerplate. Run this command and accept all the defaults for now:
-
-```bash
-$ rails new blog --api -m https://raw.githubusercontent.com/graphiti-api/graphiti_rails_template/master/all.rb
-```
-
-Feel free to run `git diff` if you're interested in the
-particulars. This is mostly installing gems and including modules.
-
-> Note: if a network issue prevents you from pointing to this URL
-> directly, you can download the file and and run this command as `-m
-> /path/to/template`
-
-Alternatively, you can [**add to an existing project**](/getting-started/installation#adding-to-an-existing-app).
-
-## Defining a Resource {#defining-a-resource}
-
-A [**Resource**](/concepts/resources) defines how to query and persist your [**Model**](/concepts/backends-and-models). In other
-words: a Model is to the database as Resource is to the API. So
-first, let's define our Model:
-
-```bash
-$ bundle exec rails generate model Post title:string upvotes:integer active:boolean
-$ bundle exec rails db:migrate
-```
-
-Now we can use the built-in [generator](/concepts/resources#generators) to define our Resource,
-corresponding [**Endpoint**](/concepts/endpoints), and
-[**Integration Tests**](/topics/testing).
-
-```bash
-$ bundle exec rails g graphiti:resource Post title:string upvotes:integer active:boolean
-```
-
-You'll see a number of files created. Now run your app!:
-
-```bash
-$ bundle exec rails s
-```
-
-Verify `http://localhost:3000/api/v1/posts` renders JSON correctly.
-Now we need data.
-
-##### Seeding Data {#seeding-data}
-
-Edit `db/seeds.rb` to create a few `Post`s:
-
-```ruby
-Post.create!(title: 'My title', upvotes: 10, active: true)
-Post.create!(title: 'Another title', upvotes: 20, active: false)
-Post.create!(title: 'OMG! A title', upvotes: 30, active: true)
-```
-
-And run the script:
-
-```bash
-$ bundle exec rails db:seed
-```
-
-Now load `http://localhost:3000/api/v1/posts`. You should have 3 `Post`s in
-your database.
-
-
-
-<hr />
-
-## Querying {#querying}
-
-Now that we've defined our Resource and seeded some data, let's see
-what query functionality we have. We've listed all `Post`s at `http://localhost:3000/api/v1/posts`. Let's see what we can do:
-
-| What you want | URL |
-| --- | --- |
-| Sort by title, ascending | `/api/v1/posts?sort=title` |
-| Sort by title, descending | `/api/v1/posts?sort=-title` |
-| Paginate, 2 per page | `/api/v1/posts?page[size]=2` |
-| Paginate, 2 per page, second page | `/api/v1/posts?page[size]=2&page[number]=2` |
-| Sparse fieldset: only `title` | `/api/v1/posts?fields[posts]=title` |
-| Filter, simple equality | `/api/v1/posts?filter[title]=my title` |
-| Filter, case-insensitive equality | `/api/v1/posts?filter[title][eql]=My title` |
-| Filter, prefix | `/api/v1/posts?filter[title][prefix]=my` |
-| Filter, suffix | `/api/v1/posts?filter[title][suffix]=title` |
-| Filter, contains | `/api/v1/posts?filter[title][match]=itl` |
-| Filter, greater than | `/api/v1/posts?filter[upvotes][gt]=20` |
-| Filter, greater than or equal to | `/api/v1/posts?filter[upvotes][gte]=20` |
-| Filter, less than | `/api/v1/posts?filter[upvotes][lt]=20` |
-| Filter, less than or equal to | `/api/v1/posts?filter[upvotes][lte]=20` |
-
-Filtering on an attribute you haven't made filterable raises `Graphiti::Errors::InvalidAttributeAccess`. Filtering on one that doesn't exist raises `Graphiti::Errors::UnknownAttribute`. All filter logic can be customized, and customizations can be packaged into an **Adapter** for reuse. See [Filter](/concepts/resources#filter).
-
-### Extra Fields
-
-Some fields are expensive enough that you only want to compute them when a client asks. Declare those with `extra_attribute`:
-
-```ruby
-# app/resources/post_resource.rb
-extra_attribute :description, :string do
-  @object.active? ? 'Active Post' : 'Inactive Post'
-end
-```
-
-Request it with `/api/v1/posts?extra_fields[posts]=description`. You can also eager load data conditionally when the field is requested.
-
-### Statistics
-
-Useful for search grids ("the first 10 active posts, plus the total count of all posts") in a single request. Hit `/api/v1/posts?stats[total]=count` and the result arrives in the `meta` section of the response:
-
-![meta_total_count](/assets/img/meta_total_count.png)
-
-Statistics respect your filters, so the count adjusts accordingly. There are several built-in stats and you can [add your own](/concepts/resources#statistics).
-
-### Error Handling
-
-Your app always renders a JSONAPI-compliant error response. Raise something in the controller:
-
-```ruby
-# app/controllers/posts_controller.rb
-def index
-  raise 'foo'
-end
-```
-
-and this is what you'd see in production:
-
-![error_payload](/assets/img/error_payload.png)
-
-Different errors can be given different response codes, JSON, and side effects. See [Error Handling](/topics/error-handling).
-
-## Persisting {#persisting}
-
-Resources can Create, Update, and Delete (and you can persist multiple
-Resources in a single request). The best way to observe this behavior is
-to take a look at the tests the generator created. One example:
-
-```ruby
-# spec/api/v1/employees/create_spec.rb
-subject(:make_request) do
-  jsonapi_post "/api/v1/employees", payload
-end
-
-describe 'basic create' do
-  let(:payload) do
-    {
-      data: {
-        type: 'employees',
-        attributes: {
-          first_name: 'Jane'
-        }
-      }
-    }
-  end
-
-  it 'works' do
-    expect(EmployeeResource).to receive(:build).and_call_original
-    expect {
-      make_request
-    }.to change { Employee.count }.by(1)
-    expect(response.status).to eq(201)
-  end
-end
-```
-
-Read more about [Persistence](/concepts/persisting) and
-[Testing Persistence](/topics/testing#writes).
-
-## Adding Relationships {#adding-relationships}
-
-Let’s start by defining our Model:
-
-```bash
-$ bundle exec rails g model Comment post_id:integer body:text active:boolean
-$ bundle exec rails db:migrate
-```
-
-```ruby
-# app/models/post.rb
-has_many :comments
-
-# app/models/comment.rb
-belongs_to :post
-```
-
-...and corresponding Resource object:
-
-```bash
-$ bundle exec rails g graphiti:resource Comment body:string active:boolean created_at:datetime
-```
-
-Configure the relationship in `PostResource`:
-
-```ruby
-# app/resources/post_resource.rb
-has_many :comments
-```
-
-And allow filtering Comments based on the Post `id`:
-
-```ruby
-# app/resources/comment_resource.rb
-attribute :post_id, :integer, only: [:filterable]
-```
-
-This code:
-
-* Allows eager-loading the relationship.
-  * URL: `/api/v1/posts?include=comments`
-  * SQL: `SELECT * FROM comments WHERE post_id = 123`
-* Generates a [**Link**](/concepts/links) for
-lazy-loading.
-* Will use `CommentResource` for querying logic (so we can [Deep
-Query](/concepts/relationships#deep-queries), e.g.
-"only return the latest 3 active comments").
-* By default, this will generate the query `CommentResource.all(filter: { post_id: 123 })`, but [relationships can be customized](/concepts/relationships)
-
-You should now be able to hit `/api/v1/comments` with all the same
-functionality as before. We need to seed data.
-
-#### Seeding Relationships {#seeding-relationships}
-
-Start by clearing out your database:
-
-```bash
-$ bundle exec rails db:migrate:reset
-```
-
-Replace your `db/seeds.rb` with this code to persist one `Post` and three `Comment`s:
-
-```ruby
-comment1 = Comment.new(body: 'comment one', active: true)
-comment2 = Comment.new(body: 'comment two', active: false)
-comment3 = Comment.new(body: 'comment three', active: true)
-
-Post.create! \
-  title: 'My title!',
-  active: true,
-  comments: [comment1, comment2, comment3]
-```
-
-And run it:
-
-```bash
-$ bundle exec rails db:seed
-```
-
-## Relationship Usage {#relationship-usage}
-
-Now let's fetch a `Post` and filtered `Comment`s in a single request:
-
-`/api/v1/posts?include=comments`
-
-Any logic in `CommentResource` is available to us. Let's sort the comments by `created_at` descending:
-
-`/api/v1/posts?include=comments&sort=-comments.created_at`.
-
-Logic from `CommentResource` is accessible at the `/api/v1/comments` endpoint, and reusable when eager-loading Comments at `/api/v1/posts:`
-
-* `/api/v1/comments?filter[active]=true`
-* `/api/v1/posts?include=comments&filter[comments.active]=true`
-
-This is why Resource objects exist: they provide an interface to
-reuse code across multiple Endpoints.
-
-Just as we can query a graph of Resources in a single
-request, we can *persist* a graph of Resources in a single request. See
-[Sideposting](/concepts/persisting#sideposting).
-
-## Exploring with Vandal {#exploring-with-vandal}
-
-Graphiti ships with Vandal, a UI that introspects your schema for point-and-click data exploration. See the [Vandal Guide](/reference/vandal) to try it against this blog.
-
-## Next Steps {#whats-next}
-
-* Continue with the [Tutorial](/tutorial) for a deeper walkthrough of customization and relationships.
-* Browse the [Resources guide](/) for the full capability reference.
-* Read the [Testing Guide](/topics/testing) to start testing your API.

data/docs/getting-started/installation.md

@@ -1,185 +0,0 @@
----
-title: 'Installation'
----
-
-## From Scratch {#from-scratch}
-
-The easiest way to start from scratch is to use the application
-template:
-
-```bash
-$ rails new blog --api -m https://raw.githubusercontent.com/graphiti-api/graphiti_rails_template/master/all.rb
-```
-
-Alternatively, download and point to the template locally:
-
-```bash
-$ curl -O https://raw.githubusercontent.com/graphiti-api/graphiti_rails_template/master/all.rb
-$ rails new blog --api -m all.rb
-```
-
-Run `git diff` to see the changes to a blank Rails app.
-
-## Adding to an Existing App {#adding-to-an-existing-app}
-
-This process is straightforward. You can add Graphiti to an existing
-Rails app alongside [JBuilder](https://github.com/rails/jbuilder) or [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers).
-
-Start with gems:
-
-```ruby
-# The only strictly-required gem
-gem 'graphiti'
-
-# For automatic ActiveRecord pagination
-gem 'kaminari'
-
-# Test-specific gems
-group :development, :test do
-  gem 'rspec-rails'
-  gem 'factory_bot_rails'
-  gem 'faker'
-end
-
-group :test do
-  gem 'database_cleaner'
-end
-```
-
-You'll be up-and-running at this point. Verify with a simple standalone
-Resource:
-
-```ruby
-# Assuming you already have a Post ActiveRecord Model
-class PostResource < Graphiti::Resource
-  self.adapter = Graphiti::Adapters::ActiveRecord
-  attribute :title, :string
-end
-
-PostResource.all.data # => [#<Post>, #<Post>, ...]
-```
-
-Now we need to integrate with Rails endpoints (to give us things
-like [#context](/concepts/resources#context)):
-
-```ruby
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  include Graphiti::Rails::Controller
-end
-```
-
-And wire-up our error-handling:
-
-```ruby
-# app/controllers/application_controller.rb
-# When #show action does not find record, return 404
-register_exception Graphiti::Errors::RecordNotFound,
-  status: 404
-
-rescue_from Exception do |e|
-  handle_exception(e)
-end
-```
-
-That's it for the basics. You may have issues with generators
-conflicting with your existing application structure - but you can
-always write files manually or [submit an issue](https://github.com/graphiti-api/graphiti/issues).
-
-### Responders {#responders}
-
-Graphiti supports JSONAPI, simple JSON, and XML. You can do this
-manually when inheriting from `ActionController::Base`
-
-```ruby
-def index
-  posts = PostResource.all(params)
-
-  respond_to do |format|
-    format.json { render(json: posts) }
-    format.jsonapi { render(jsonapi: posts) }
-    format.xml { render(xml: posts) }
-  end
-end
-```
-
-But we can inherit from `ActionController::API` while avoiding this
-boilerplate with with the [Responders](https://github.com/plataformatec/responders) gem:
-
-```ruby
-def index
-  posts = PostResource.all(params)
-  respond_with(posts)
-end
-```
-
-To get this functionality:
-
-```ruby
-# Gemfile
-gem 'responders'
-
-# app/controllers/application_controller.rb
-include Graphiti::Rails::Responders
-```
-
-> Note: Persistence operations only support JSONAPI format, so you'll
-> still use `render jsonapi:` and `render jsonapi_errors:` for those.
-
-### .graphiticfg.yml {#graphiticfg}
-
-The `.graphiticfg.yml` file lives in the root directory of your
-application. It holds configuration we need to reuse across a variety of
-contexts (primarily generates and rake tasks). If you use our template to create your application, it's created for you.
-
-Primarily this is used to hold your "API namespace":
-
-```yaml
-namespace: /my_api/v1
-```
-
-If this file doesn't exist you may get unexpected errors - make sure to
-create it!
-
-### Testing {#testing}
-
-To add our [Integration Tests](/topics/testing):
-
-```ruby
-# Gemfile
-group :development, :test do
-  gem 'factory_bot_rails'
-  gem 'rspec_rails'
-  gem 'faker'
-end
-
-group :test do
-  gem 'database_cleaner'
-end
-```
-
-Bootstrap RSpec if you haven't already:
-
-```bash
-$ bin/rails g rspec:install
-```
-
-Then add the Graphiti spec helpers and database cleaning to your `RSpec.configure` block. See [RSpec Setup](/topics/testing#rspec) in the Testing guide for the config to paste in.
-
-### will_paginate {#will-paginate}
-
-By default, we use [Kaminari](https://github.com/kaminari/kaminari) for
-ActiveRecord pagination. If you prefer [will_paginate] (or anything
-else):
-
-```ruby
-# app/resources/application_resource.rb
-paginate do |scope, current_page, per_page|
-  scope.paginate(page: current_page, per_page: per_page)
-end
-```
-
-## Without Rails {#without-rails}
-
-You can use Graphiti in any plain `.rb` file. To see this in action,
-check out the [Plain Ruby Sample App](https://github.com/graphiti-api/plain_ruby_example).