Skip to content

docs: Add pagination links docs #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+79 −14
Open

docs: Add pagination links docs #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba6d0e9
docs: Add pagination links docs
marcelobarreto May 10, 2021
6c93919
fix: pagination documentation
marcelobarreto May 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions _site/cookbooks/without-activerecord.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ <h2>
mind the premise of building a hash of options and passing it off to a
client can apply to any datastore).</p>

<p>Finally, we’re <a href="/graphiti/guides/concepts/resources#resolve">resolving that scope</a>,
<p>Finally, we’re <a href="https://www.graphiti.dev/guides/concepts/resources#resolve">resolving that scope</a>,
returning the full dataset for now. The contract of <code class="highlighter-rouge">#resolve</code> is to
return an array of model instances, hence <code class="highlighter-rouge">DATA.map { |d| Post.new(d)
}</code>.</p>
Expand Down Expand Up @@ -298,7 +298,7 @@ <h4>

<p>These are the overrides for persistence operations. You are encouraged
<strong>not</strong> to override <code class="highlighter-rouge">create/update/destroy</code> directly and instead use
<a href="https://www.graphiti.dev/concepts/resources#persistence-lifecycle-hooks">Persistence Lifecycle Hooks</a>.</p>
<a href="https://www.graphiti.dev/guides/concepts/resources#persistence-lifecycle-hooks">Persistence Lifecycle Hooks</a>.</p>

<a class="anchor" id="adapters" />
<a class="header" href="#adapters">
Expand Down
10 changes: 5 additions & 5 deletions _site/feed.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="3.3.1">Jekyll</generator><link href="/feed.xml" rel="self" type="application/atom+xml" /><link href="/" rel="alternate" type="text/html" /><updated>2020-05-29T10:03:07-04:00</updated><id>/</id><title type="html">Graphiti</title><subtitle>Stylish Graph APIs
</subtitle><entry><title type="html">Tutorial Write-Ups Are Out!</title><link href="/2019/10/14/tutorial.html" rel="alternate" type="text/html" title="Tutorial Write-Ups Are Out!" /><published>2019-10-14T00:00:00-04:00</published><updated>2019-10-14T00:00:00-04:00</updated><id>/2019/10/14/tutorial</id><content type="html" xml:base="/2019/10/14/tutorial.html">&lt;p&gt;Though we’ve long had a &lt;a href=&quot;https://github.com/graphiti-api/employee_directory&quot;&gt;sample application&lt;/a&gt; with step-by-step diffs, we’ve been missing a full walkthrough. That now exists! Start with &lt;a href=&quot;https://www.graphiti.dev/tutorial/step_0&quot;&gt;Step 0: Bootstrapping&lt;/a&gt;.&lt;/p&gt;
<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="3.3.1">Jekyll</generator><link href="http://localhost:4000/feed.xml" rel="self" type="application/atom+xml" /><link href="http://localhost:4000/" rel="alternate" type="text/html" /><updated>2021-05-15T10:00:38-03:00</updated><id>http://localhost:4000/feed.xml</id><title type="html">Graphiti</title><subtitle>Stylish Graph APIs
</subtitle><entry><title type="html">Tutorial Write-Ups Are Out!</title><link href="http://localhost:4000/2019/10/14/tutorial.html" rel="alternate" type="text/html" title="Tutorial Write-Ups Are Out!" /><published>2019-10-14T00:00:00-03:00</published><updated>2019-10-14T00:00:00-03:00</updated><id>http://localhost:4000/2019/10/14/tutorial</id><content type="html" xml:base="http://localhost:4000/2019/10/14/tutorial.html">&lt;p&gt;Though we’ve long had a &lt;a href=&quot;https://github.com/graphiti-api/employee_directory&quot;&gt;sample application&lt;/a&gt; with step-by-step diffs, we’ve been missing a full walkthrough. That now exists! Start with &lt;a href=&quot;https://www.graphiti.dev/tutorial/step_0&quot;&gt;Step 0: Bootstrapping&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;These write-ups will tell you the relevant code and commands, but
they’ll also give helpful context around the decisions Graphiti makes.
Expand All @@ -15,7 +15,7 @@ Even if you’re already a Graphiti user, I suggest checking it out!&lt;/p&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;&lt;/p&gt;</content><author><name>Lee Richmond</name></author><summary type="html">Though we’ve long had a sample application with step-by-step diffs, we’ve been missing a full walkthrough. That now exists! Start with Step 0: Bootstrapping.</summary></entry><entry><title type="html">Graphiti 1.2 Released</title><link href="/2019/05/20/graphiti-1-2.html" rel="alternate" type="text/html" title="Graphiti 1.2 Released" /><published>2019-05-20T00:00:00-04:00</published><updated>2019-05-20T00:00:00-04:00</updated><id>/2019/05/20/graphiti-1-2</id><content type="html" xml:base="/2019/05/20/graphiti-1-2.html">&lt;p&gt;I’m thrilled to announce much-needed, much-improved Rails integration,
&lt;br /&gt;&lt;/p&gt;</content><author><name>Lee Richmond</name></author><summary type="html">Though we’ve long had a sample application with step-by-step diffs, we’ve been missing a full walkthrough. That now exists! Start with Step 0: Bootstrapping.</summary></entry><entry><title type="html">Graphiti 1.2 Released</title><link href="http://localhost:4000/2019/05/20/graphiti-1-2.html" rel="alternate" type="text/html" title="Graphiti 1.2 Released" /><published>2019-05-20T00:00:00-03:00</published><updated>2019-05-20T00:00:00-03:00</updated><id>http://localhost:4000/2019/05/20/graphiti-1-2</id><content type="html" xml:base="http://localhost:4000/2019/05/20/graphiti-1-2.html">&lt;p&gt;I’m thrilled to announce much-needed, much-improved Rails integration,
courtesy of the amazing &lt;a href=&quot;https://github.com/wagenet&quot;&gt;Peter Wagenet&lt;/a&gt; and
the new &lt;a href=&quot;https://github.com/graphiti-api/graphiti-rails&quot;&gt;graphiti-rails&lt;/a&gt; gem.
This gives us better error handling, tighter controllers, and a solid
Expand Down Expand Up @@ -48,7 +48,7 @@ channels in our &lt;a href=&quot;https://join.slack.com/t/graphiti-api/shared_in
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;&lt;/p&gt;</content><author><name>Lee Richmond</name></author><summary type="html">I’m thrilled to announce much-needed, much-improved Rails integration, courtesy of the amazing Peter Wagenet and the new graphiti-rails gem. This gives us better error handling, tighter controllers, and a solid foundation for the codebase moving forward.</summary></entry><entry><title type="html">Graphiti 1.1 Released</title><link href="/2019/05/08/graphiti-1-1.html" rel="alternate" type="text/html" title="Graphiti 1.1 Released" /><published>2019-05-08T00:00:00-04:00</published><updated>2019-05-08T00:00:00-04:00</updated><id>/2019/05/08/graphiti-1-1</id><content type="html" xml:base="/2019/05/08/graphiti-1-1.html">&lt;p&gt;Our first minor version bump centers around an important update:
&lt;br /&gt;&lt;/p&gt;</content><author><name>Lee Richmond</name></author><summary type="html">I’m thrilled to announce much-needed, much-improved Rails integration, courtesy of the amazing Peter Wagenet and the new graphiti-rails gem. This gives us better error handling, tighter controllers, and a solid foundation for the codebase moving forward.</summary></entry><entry><title type="html">Graphiti 1.1 Released</title><link href="http://localhost:4000/2019/05/08/graphiti-1-1.html" rel="alternate" type="text/html" title="Graphiti 1.1 Released" /><published>2019-05-08T00:00:00-03:00</published><updated>2019-05-08T00:00:00-03:00</updated><id>http://localhost:4000/2019/05/08/graphiti-1-1</id><content type="html" xml:base="http://localhost:4000/2019/05/08/graphiti-1-1.html">&lt;p&gt;Our first minor version bump centers around an important update:
&lt;strong&gt;better errors for clients&lt;/strong&gt;. This is the first phase of work to allow us to provide more actionable errors to API users who might not also be developers of the API itself. This was brought to us by Graphiti maintainer &lt;a href=&quot;https://github.com/wadetandy&quot;&gt;Wade Tandy&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Previously, when a client sent a bad write request to the server -
Expand Down Expand Up @@ -79,7 +79,7 @@ will be extendable to reads as well.&lt;/p&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;&lt;/p&gt;</content><author><name>Lee Richmond</name></author><summary type="html">Our first minor version bump centers around an important update: better errors for clients. This is the first phase of work to allow us to provide more actionable errors to API users who might not also be developers of the API itself. This was brought to us by Graphiti maintainer Wade Tandy.</summary></entry><entry><title type="html">Graphiti 1.0 Released 🎉</title><link href="/2019/03/31/graphiti-1-0.html" rel="alternate" type="text/html" title="Graphiti 1.0 Released 🎉" /><published>2019-03-31T00:00:00-04:00</published><updated>2019-03-31T00:00:00-04:00</updated><id>/2019/03/31/graphiti-1-0</id><content type="html" xml:base="/2019/03/31/graphiti-1-0.html">&lt;p&gt;This project has gone through a number of iterations over the past three years. I’m happy to say we’ve now released 1.0, committing to semantic versioning. Graphiti has now seen enough use, across a wide variety of scenarios, that we can commit to no backwards-incompatible changes for a long while, and a changelog for future releases.&lt;/p&gt;
&lt;br /&gt;&lt;/p&gt;</content><author><name>Lee Richmond</name></author><summary type="html">Our first minor version bump centers around an important update: better errors for clients. This is the first phase of work to allow us to provide more actionable errors to API users who might not also be developers of the API itself. This was brought to us by Graphiti maintainer Wade Tandy.</summary></entry><entry><title type="html">Graphiti 1.0 Released 🎉</title><link href="http://localhost:4000/2019/03/31/graphiti-1-0.html" rel="alternate" type="text/html" title="Graphiti 1.0 Released 🎉" /><published>2019-03-31T00:00:00-03:00</published><updated>2019-03-31T00:00:00-03:00</updated><id>http://localhost:4000/2019/03/31/graphiti-1-0</id><content type="html" xml:base="http://localhost:4000/2019/03/31/graphiti-1-0.html">&lt;p&gt;This project has gone through a number of iterations over the past three years. I’m happy to say we’ve now released 1.0, committing to semantic versioning. Graphiti has now seen enough use, across a wide variety of scenarios, that we can commit to no backwards-incompatible changes for a long while, and a changelog for future releases.&lt;/p&gt;

&lt;p&gt;We’ll be writing more in this blog about our future roadmap. Stay tuned!&lt;/p&gt;

Expand Down
40 changes: 39 additions & 1 deletion _site/guides/concepts/links.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ <h1 id="links">Links</h1>
<li><a href="#autolinking">Autolinking</a></li>
<li><a href="#endpoint-validation">Endpoint Validation</a></li>
<li><a href="#links-on-demand">Links-On-Demand</a></li>
<li><a href="#pagination-links">Pagination Links</a></li>
<li><a href="#custom-endpoint-urls">Custom Endpoint URLs</a></li>
</ul>
</li>
Expand Down Expand Up @@ -333,10 +334,47 @@ <h3>
<span class="n">c</span><span class="p">.</span><span class="nf">links_on_demand</span> <span class="o">=</span> <span class="kp">true</span>
<span class="k">end</span></code></pre></figure>

<a class="anchor" id="pagination-links" />
<a class="header" href="#pagination-links">
<h3>
3.4 Pagination Links
</h3>
</a>

<p>Requesting big collections can result into slow responses sometimes. In order to avoid this, you could use <a href="https://jsonapi.org/format/#fetching-pagination">pagination</a>. It’ll break your response into smaller pieces that will make your server responds faster. Paginations links can be present in your response in the following ways:</p>

<a class="anchor" id="pagination-links-showing-by-default" />
<a class="header" href="#pagination-links-showing-by-default">
<h4>
3.4.1 Showing by default
</h4>
</a>

<p>With this configuration, all the responses will return the pagination links</p>

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="no">Graphiti</span><span class="p">.</span><span class="nf">configure</span> <span class="k">do</span> <span class="o">|</span><span class="n">c</span><span class="o">|</span>
<span class="n">c</span><span class="p">.</span><span class="nf">pagination_links</span> <span class="o">=</span> <span class="kp">true</span>
<span class="k">end</span></code></pre></figure>

<a class="anchor" id="pagination-links-when-requested" />
<a class="header" href="#pagination-links-when-requested">
<h4>
3.4.2 When requested
</h4>
</a>

<p>You can showing the pagination links when it was requested in the URL with <code class="highlighter-rouge">?pagination_links=true</code></p>

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="no">Graphiti</span><span class="p">.</span><span class="nf">configure</span> <span class="k">do</span> <span class="o">|</span><span class="n">c</span><span class="o">|</span>
<span class="n">c</span><span class="p">.</span><span class="nf">pagination_links_on_demand</span> <span class="o">=</span> <span class="kp">true</span>
<span class="k">end</span></code></pre></figure>

<p>Pagination links won’t show up for <em>#show</em> actions.</p>

<a class="anchor" id="custom-endpoint-urls" />
<a class="header" href="#custom-endpoint-urls">
<h3>
3.4 Custom Endpoint URLs
3.5 Custom Endpoint URLs
</h3>
</a>

Expand Down
10 changes: 5 additions & 5 deletions _site/guides/concepts/resources.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ <h4>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">attribute</span> <span class="ss">:name</span><span class="p">,</span> <span class="ss">:string</span><span class="p">,</span> <span class="ss">only: </span><span class="p">[</span><span class="ss">:sortable</span><span class="p">]</span>
<span class="n">attribute</span> <span class="ss">:name</span><span class="p">,</span> <span class="ss">:string</span><span class="p">,</span> <span class="ss">except: </span><span class="p">[</span><span class="ss">:writable</span><span class="p">]</span></code></pre></figure>

<p>The <code class="highlighter-rouge">schema</code> flag is not affected by <code class="highlighter-rouge">only/except</code> options.
<p>The <code class="highlighter-rouge">schema</code> flag is not affected by <code class="highlighter-rouge">only/except</code> options.
This option determines if the attribute is exported to the schema.json.</p>

<p>You might want to allow behavior only if a certain condition is met.
Expand Down Expand Up @@ -771,7 +771,7 @@ <h5>
<p>If a filter is marked <code class="highlighter-rouge">single: true</code>, we’ll avoid any array parsing and
escape the value for you, filtering on the string as given.</p>

<p>By default a value that comes in as <code class="highlighter-rouge">null</code> is treated as a string <code class="highlighter-rouge">"null"</code>.
<p>By default a value that comes in as <code class="highlighter-rouge">null</code> is treated as a string <code class="highlighter-rouge">"null"</code>.
To coerce <code class="highlighter-rouge">null</code> to a Ruby <code class="highlighter-rouge">nil</code> mark the filter with <code class="highlighter-rouge">allow_nil: true</code>.
This can be changed for all attributes by setting <code class="highlighter-rouge">filters_accept_nil_by_default</code></p>

Expand Down Expand Up @@ -1264,7 +1264,7 @@ <h5>

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># app/models/employee.rb</span>
<span class="n">has_many</span> <span class="ss">:positions</span>
<span class="n">has_one</span> <span class="ss">:current_position</span><span class="p">,</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="n">where</span><span class="p">(</span><span class="ss">created_at: :desc</span><span class="p">)</span> <span class="p">}</span>
<span class="n">has_one</span> <span class="ss">:current_position</span><span class="p">,</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="n">where</span><span class="p">(</span><span class="ss">created_at: :desc</span><span class="p">)</span> <span class="p">},</span> <span class="ss">class_name: </span><span class="s1">'Position'</span>

<span class="no">Employee</span><span class="p">.</span><span class="nf">includes</span><span class="p">(</span><span class="s1">'current_position'</span><span class="p">).</span><span class="nf">to_a</span>

Expand All @@ -1279,7 +1279,7 @@ <h5>

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># app/resources/employee_resource.rb</span>
<span class="n">has_many</span> <span class="ss">:positions</span>
<span class="n">has_one</span> <span class="ss">:current_position</span> <span class="k">do</span>
<span class="n">has_one</span> <span class="ss">:current_position</span><span class="p">,</span> <span class="ss">resource: </span><span class="no">PositionResource</span> <span class="k">do</span>
<span class="n">params</span> <span class="k">do</span> <span class="o">|</span><span class="nb">hash</span><span class="o">|</span>
<span class="nb">hash</span><span class="p">[</span><span class="ss">:sort</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'-created_at'</span>
<span class="k">end</span>
Expand All @@ -1302,7 +1302,7 @@ <h5>

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># app/models/employee.rb</span>
<span class="n">has_many</span> <span class="ss">:positions</span>
<span class="n">has_one</span> <span class="ss">:current_position</span><span class="p">,</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="n">where</span><span class="p">(</span><span class="ss">historical_index: </span><span class="mi">1</span><span class="p">)</span> <span class="p">}</span>
<span class="n">has_one</span> <span class="ss">:current_position</span><span class="p">,</span> <span class="o">-&gt;</span> <span class="p">{</span> <span class="n">where</span><span class="p">(</span><span class="ss">historical_index: </span><span class="mi">1</span><span class="p">)</span> <span class="p">},</span> <span class="ss">class_name: </span><span class="s1">'Position'</span>

<span class="no">Employee</span><span class="p">.</span><span class="nf">includes</span><span class="p">(</span><span class="s1">'current_position'</span><span class="p">).</span><span class="nf">to_a</span>

Expand Down
29 changes: 28 additions & 1 deletion guides/concepts/links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Links
* [Autolinking](#autolinking)
* [Endpoint Validation](#endpoint-validation)
* [Links-On-Demand](#links-on-demand)
* [Pagination Links](#pagination-links)
* [Custom Endpoint URLs](#custom-endpoint-urls)

</div>
Expand Down Expand Up @@ -225,7 +226,33 @@ Graphiti.configure do |c|
end
{% endhighlight %}

{% include h.html tag="h3" text="3.4 Custom Endpoint URLs" a="custom-endpoint-urls" %}
{% include h.html tag="h3" text="3.4 Pagination Links" a="pagination-links" %}

Requesting big collections can result into slow responses sometimes. In order to avoid this, you could use [pagination](https://jsonapi.org/format/#fetching-pagination). It'll break your response into smaller pieces that will make your server responds faster. Paginations links can be present in your response in the following ways:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is true, but rendering links is different from paginating in general. Personally I don't render the links, but I use page[size], page[number] and stats[total]=count to do the same. I think the benefit here is a little less burden on the client.


{% include h.html tag="h4" text="3.4.1 Showing by default" a="pagination-links-showing-by-default" %}

With this configuration, all the responses will return the pagination links
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For brevity, I would change to "Globally:"


{% highlight ruby %}
Graphiti.configure do |c|
c.pagination_links = true
end
{% endhighlight %}

{% include h.html tag="h4" text="3.4.2 When requested" a="pagination-links-when-requested" %}

You can showing the pagination links when it was requested in the URL with `?pagination_links=true`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Or on-demand when requested in the URL with ?pagination_links=true"


{% highlight ruby %}
Graphiti.configure do |c|
c.pagination_links_on_demand = true
end
{% endhighlight %}

Pagination links won't show up for *#show* actions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can remove this line - should already be an expectation, their presence is a bug.


{% include h.html tag="h3" text="3.5 Custom Endpoint URLs" a="custom-endpoint-urls" %}

To change the URL associated with a Resource:

Expand Down