graphiti 2.0.0.beta.7 → 2.0.0.beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (238) hide show
  1. checksums.yaml +4 -4
  2. data/.git-blame-ignore-revs +2 -0
  3. data/.github/workflows/ci.yml +55 -3
  4. data/.github/workflows/docs.yml +1 -1
  5. data/.github/workflows/notify-example-app.yml +18 -0
  6. data/.gitignore +2 -0
  7. data/.standard.yml +6 -0
  8. data/CHANGELOG.md +45 -0
  9. data/CONTRIBUTING.md +3 -1
  10. data/README.md +13 -206
  11. data/Rakefile +6 -3
  12. data/UPGRADING.md +1 -1
  13. data/graphiti.gemspec +8 -4
  14. data/lib/generators/graphiti/generator_mixin.rb +1 -1
  15. data/lib/generators/graphiti/install_generator.rb +1 -1
  16. data/lib/generators/graphiti/resource_generator.rb +6 -3
  17. data/lib/generators/graphiti/templates/application_resource.rb.erb +19 -0
  18. data/lib/generators/graphiti/templates/controller.rb.erb +26 -8
  19. data/lib/graphiti/audit/report.rb +6 -6
  20. data/lib/graphiti/audit.rb +3 -4
  21. data/lib/graphiti/delegates/pagination.rb +2 -2
  22. data/lib/graphiti/deserializer.rb +3 -3
  23. data/lib/graphiti/errors.rb +6 -6
  24. data/lib/graphiti/extensions/temp_id.rb +1 -1
  25. data/lib/graphiti/query.rb +3 -3
  26. data/lib/graphiti/rails/context.rb +2 -1
  27. data/lib/graphiti/rails/controller.rb +3 -0
  28. data/lib/graphiti/rails/debugging.rb +1 -1
  29. data/lib/graphiti/rails/responders.rb +2 -1
  30. data/lib/graphiti/resource/configuration.rb +1 -0
  31. data/lib/graphiti/resource/dsl.rb +2 -2
  32. data/lib/graphiti/resource/links.rb +1 -1
  33. data/lib/graphiti/resource/persistence.rb +1 -1
  34. data/lib/graphiti/resource/polymorphism.rb +1 -1
  35. data/lib/graphiti/resource.rb +2 -2
  36. data/lib/graphiti/resource_proxy.rb +0 -1
  37. data/lib/graphiti/scoping/filter.rb +5 -3
  38. data/lib/graphiti/scoping/paginate.rb +1 -1
  39. data/lib/graphiti/scoping/sort.rb +1 -1
  40. data/lib/graphiti/sideload/has_many.rb +1 -1
  41. data/lib/graphiti/spec_helpers/errors_proxy.rb +1 -1
  42. data/lib/graphiti/spec_helpers/matchers.rb +1 -1
  43. data/lib/graphiti/types.rb +5 -1
  44. data/lib/graphiti/util/cache_debug.rb +3 -3
  45. data/lib/graphiti/util/hash.rb +1 -1
  46. data/lib/graphiti/util/persistence.rb +6 -6
  47. data/lib/graphiti/util/serializer_relationships.rb +1 -1
  48. data/lib/graphiti/version.rb +1 -1
  49. data/lib/tasks/graphiti.rake +1 -1
  50. metadata +31 -197
  51. data/docs/concepts/backends-and-models.md +0 -122
  52. data/docs/concepts/endpoints.md +0 -183
  53. data/docs/concepts/links.md +0 -212
  54. data/docs/concepts/overview.md +0 -80
  55. data/docs/concepts/persisting.md +0 -376
  56. data/docs/concepts/relationships.md +0 -627
  57. data/docs/concepts/resources.md +0 -677
  58. data/docs/getting-started/first-api.md +0 -289
  59. data/docs/getting-started/installation.md +0 -185
  60. data/docs/intro.md +0 -307
  61. data/docs/js/authentication.md +0 -63
  62. data/docs/js/ddau.md +0 -20
  63. data/docs/js/extra-params.md +0 -41
  64. data/docs/js/index.md +0 -112
  65. data/docs/js/installation.md +0 -120
  66. data/docs/js/middleware.md +0 -72
  67. data/docs/js/models.md +0 -202
  68. data/docs/js/reads.md +0 -494
  69. data/docs/js/state-syncing.md +0 -100
  70. data/docs/js/writes.md +0 -373
  71. data/docs/reference/vandal.md +0 -63
  72. data/docs/reference/why.md +0 -13
  73. data/docs/topics/authorization.md +0 -155
  74. data/docs/topics/caching.md +0 -55
  75. data/docs/topics/customizing-sideloads.md +0 -156
  76. data/docs/topics/debugging.md +0 -242
  77. data/docs/topics/error-handling.md +0 -210
  78. data/docs/topics/etags.md +0 -46
  79. data/docs/topics/hopping-relationships.md +0 -149
  80. data/docs/topics/json-attributes.md +0 -77
  81. data/docs/topics/openstruct-models.md +0 -50
  82. data/docs/topics/remote-resources.md +0 -291
  83. data/docs/topics/testing.md +0 -916
  84. data/docs/topics/without-activerecord.md +0 -324
  85. data/docs/tutorial/index.md +0 -58
  86. data/docs/tutorial/step_0.md +0 -107
  87. data/docs/tutorial/step_1.md +0 -199
  88. data/docs/tutorial/step_2.md +0 -312
  89. data/docs/tutorial/step_3.md +0 -142
  90. data/docs/tutorial/step_4.md +0 -135
  91. data/docs/tutorial/step_5.md +0 -69
  92. data/docs/tutorial/step_6.md +0 -82
  93. data/docs/tutorial/step_7.md +0 -205
  94. data/docs/tutorial/step_8.md +0 -128
  95. data/docs/tutorial/step_9.md +0 -171
  96. data/docs/upgrading.md +0 -267
  97. data/website/.gitignore +0 -20
  98. data/website/README.md +0 -43
  99. data/website/docusaurus.config.js +0 -197
  100. data/website/package-lock.json +0 -19474
  101. data/website/package.json +0 -46
  102. data/website/sidebars.js +0 -82
  103. data/website/src/css/custom.css +0 -85
  104. data/website/src/pages/markdown-page.mdx +0 -7
  105. data/website/static/.nojekyll +0 -0
  106. data/website/static/1.13/2019/03/31/graphiti-1-0.html +0 -205
  107. data/website/static/1.13/2019/05/08/graphiti-1-1.html +0 -212
  108. data/website/static/1.13/2019/05/20/graphiti-1-2.html +0 -214
  109. data/website/static/1.13/2019/10/14/tutorial.html +0 -198
  110. data/website/static/1.13/CNAME +0 -1
  111. data/website/static/1.13/README.md +0 -16
  112. data/website/static/1.13/assets/css/syntax.css +0 -60
  113. data/website/static/1.13/assets/favicons/android-chrome-192x192.png +0 -0
  114. data/website/static/1.13/assets/favicons/android-chrome-256x256.png +0 -0
  115. data/website/static/1.13/assets/favicons/apple-touch-icon.png +0 -0
  116. data/website/static/1.13/assets/favicons/browserconfig.xml +0 -9
  117. data/website/static/1.13/assets/favicons/favicon-16x16.png +0 -0
  118. data/website/static/1.13/assets/favicons/favicon-32x32.png +0 -0
  119. data/website/static/1.13/assets/favicons/favicon.ico +0 -0
  120. data/website/static/1.13/assets/favicons/mstile-150x150.png +0 -0
  121. data/website/static/1.13/assets/favicons/safari-pinned-tab.svg +0 -1
  122. data/website/static/1.13/assets/favicons/site.webmanifest +0 -19
  123. data/website/static/1.13/assets/img/backend.gif +0 -0
  124. data/website/static/1.13/assets/img/conformity.png +0 -0
  125. data/website/static/1.13/assets/img/error_payload.png +0 -0
  126. data/website/static/1.13/assets/img/fancy-cushion.png +0 -0
  127. data/website/static/1.13/assets/img/gh.png +0 -0
  128. data/website/static/1.13/assets/img/home-bg.jpg +0 -0
  129. data/website/static/1.13/assets/img/lifecycle.gif +0 -0
  130. data/website/static/1.13/assets/img/logo-500.png +0 -0
  131. data/website/static/1.13/assets/img/logo.png +0 -0
  132. data/website/static/1.13/assets/img/love-graffiti.jpg +0 -0
  133. data/website/static/1.13/assets/img/meta_total_count.png +0 -0
  134. data/website/static/1.13/assets/img/persist.jpg +0 -0
  135. data/website/static/1.13/assets/img/resource.gif +0 -0
  136. data/website/static/1.13/assets/img/rest-graffiti.jpg +0 -0
  137. data/website/static/1.13/assets/img/rest1.gif +0 -0
  138. data/website/static/1.13/assets/img/rest2.gif +0 -0
  139. data/website/static/1.13/assets/img/rest3.gif +0 -0
  140. data/website/static/1.13/assets/img/rethink-rest-graffiti.jpg +0 -0
  141. data/website/static/1.13/assets/img/sunrise.png +0 -0
  142. data/website/static/1.13/assets/img/why.png +0 -0
  143. data/website/static/1.13/assets/js/highlight.pack.js +0 -2
  144. data/website/static/1.13/assets/main.css +0 -15518
  145. data/website/static/1.13/assets/main.css.map +0 -1
  146. data/website/static/1.13/bin/bundle +0 -109
  147. data/website/static/1.13/bin/jekyll +0 -27
  148. data/website/static/1.13/bin/kramdown +0 -27
  149. data/website/static/1.13/bin/listen +0 -27
  150. data/website/static/1.13/bin/rake +0 -27
  151. data/website/static/1.13/bin/rougify +0 -27
  152. data/website/static/1.13/bin/safe_yaml +0 -27
  153. data/website/static/1.13/bin/sass +0 -27
  154. data/website/static/1.13/bin/sass-convert +0 -27
  155. data/website/static/1.13/bin/scss +0 -27
  156. data/website/static/1.13/blog.html +0 -259
  157. data/website/static/1.13/cheatsheet.html +0 -316
  158. data/website/static/1.13/cookbooks/authorization.md +0 -0
  159. data/website/static/1.13/cookbooks/caching.md +0 -0
  160. data/website/static/1.13/cookbooks/customizing-sideloads.html +0 -325
  161. data/website/static/1.13/cookbooks/etags.md +0 -0
  162. data/website/static/1.13/cookbooks/hopping-relationships.html +0 -324
  163. data/website/static/1.13/cookbooks/json_attributes.md +0 -0
  164. data/website/static/1.13/cookbooks/openstruct-models.md +0 -0
  165. data/website/static/1.13/cookbooks/remote-resources.md +0 -0
  166. data/website/static/1.13/cookbooks/without-activerecord.html +0 -510
  167. data/website/static/1.13/features.html +0 -249
  168. data/website/static/1.13/feed.xml +0 -106
  169. data/website/static/1.13/guides/concepts/backends-and-models.html +0 -467
  170. data/website/static/1.13/guides/concepts/debugging.html +0 -440
  171. data/website/static/1.13/guides/concepts/endpoints.html +0 -432
  172. data/website/static/1.13/guides/concepts/error-handling.html +0 -396
  173. data/website/static/1.13/guides/concepts/links.html +0 -501
  174. data/website/static/1.13/guides/concepts/remote-resources.html +0 -536
  175. data/website/static/1.13/guides/concepts/resources.html +0 -2176
  176. data/website/static/1.13/guides/concepts/testing.html +0 -1469
  177. data/website/static/1.13/guides/getting-started/installation.html +0 -420
  178. data/website/static/1.13/guides/graphiti-rails-migration.html +0 -242
  179. data/website/static/1.13/guides/index.html +0 -269
  180. data/website/static/1.13/guides/overview.html +0 -325
  181. data/website/static/1.13/guides/upgrading-2-0.html +0 -193
  182. data/website/static/1.13/guides/upgrading.html +0 -314
  183. data/website/static/1.13/guides/vandal.html +0 -282
  184. data/website/static/1.13/guides/why.html +0 -1121
  185. data/website/static/1.13/index.html +0 -72
  186. data/website/static/1.13/js/authentication.html +0 -295
  187. data/website/static/1.13/js/ddau.html +0 -238
  188. data/website/static/1.13/js/extra-params.html +0 -270
  189. data/website/static/1.13/js/index.html +0 -321
  190. data/website/static/1.13/js/installation.html +0 -637
  191. data/website/static/1.13/js/introduction.html +0 -257
  192. data/website/static/1.13/js/middleware.html +0 -318
  193. data/website/static/1.13/js/reads/fieldsets.html +0 -271
  194. data/website/static/1.13/js/reads/filtering.html +0 -289
  195. data/website/static/1.13/js/reads/includes.html +0 -260
  196. data/website/static/1.13/js/reads/index.html +0 -497
  197. data/website/static/1.13/js/reads/nested-queries.html +0 -353
  198. data/website/static/1.13/js/reads/pagination.html +0 -260
  199. data/website/static/1.13/js/reads/sorting.html +0 -265
  200. data/website/static/1.13/js/reads/statistics.html +0 -289
  201. data/website/static/1.13/js/state-syncing.html +0 -340
  202. data/website/static/1.13/js/writes/deferred.html +0 -296
  203. data/website/static/1.13/js/writes/dirty-tracking.html +0 -399
  204. data/website/static/1.13/js/writes/index.html +0 -391
  205. data/website/static/1.13/js/writes/nested.html +0 -330
  206. data/website/static/1.13/js/writes/validations.html +0 -272
  207. data/website/static/1.13/quickstart.html +0 -660
  208. data/website/static/1.13/template +0 -161
  209. data/website/static/1.13/tutorial/index.html +0 -250
  210. data/website/static/1.13/tutorial/step_0.html +0 -292
  211. data/website/static/1.13/tutorial/step_1.html +0 -517
  212. data/website/static/1.13/tutorial/step_2.html +0 -481
  213. data/website/static/1.13/tutorial/step_3.html +0 -323
  214. data/website/static/1.13/tutorial/step_4.html +0 -318
  215. data/website/static/1.13/tutorial/step_5.html +0 -265
  216. data/website/static/1.13/tutorial/step_6.html +0 -276
  217. data/website/static/1.13/tutorial/step_7.html +0 -390
  218. data/website/static/1.13/tutorial/step_8.html +0 -316
  219. data/website/static/1.13/tutorial/step_9.html +0 -365
  220. data/website/static/CNAME +0 -1
  221. data/website/static/assets/img/error_payload.png +0 -0
  222. data/website/static/assets/img/legacy/legacy-0378a3bb39.png +0 -0
  223. data/website/static/assets/img/legacy/legacy-05bbd3e5fd.png +0 -0
  224. data/website/static/assets/img/legacy/legacy-07aa104495.png +0 -0
  225. data/website/static/assets/img/legacy/legacy-0c75a16b3a.gif +0 -0
  226. data/website/static/assets/img/legacy/legacy-3076df6209.png +0 -0
  227. data/website/static/assets/img/legacy/legacy-7f6889bc89.png +0 -0
  228. data/website/static/assets/img/legacy/legacy-a2cc4363c3.png +0 -0
  229. data/website/static/assets/img/legacy/legacy-f67cfa89ab.png +0 -0
  230. data/website/static/assets/img/meta_total_count.png +0 -0
  231. data/website/static/img/docusaurus-social-card.jpg +0 -0
  232. data/website/static/img/docusaurus.png +0 -0
  233. data/website/static/img/favicon.ico +0 -0
  234. data/website/static/img/logo.png +0 -0
  235. data/website/static/img/logo.svg +0 -1
  236. data/website/static/img/undraw_docusaurus_mountain.svg +0 -171
  237. data/website/static/img/undraw_docusaurus_react.svg +0 -170
  238. data/website/static/img/undraw_docusaurus_tree.svg +0 -40
data/website/static/1.13/guides/concepts/endpoints.html DELETED
@@ -1,432 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
-
4
- <head>
5
- <meta charset="utf-8">
6
- <meta http-equiv="X-UA-Compatible" content="IE=edge">
7
- <meta name="viewport" content="width=device-width, initial-scale=1">
8
- <link href="https://fonts.googleapis.com/css?family=Roboto+Mono" rel="stylesheet">
9
- <link href="https://fonts.googleapis.com/css?family=Boogaloo" rel="stylesheet">
10
-
11
- <link rel="apple-touch-icon" sizes="180x180" href="/1.13/assets/favicons/apple-touch-icon.png">
12
- <link rel="icon" type="image/png" sizes="32x32" href="/1.13/assets/favicons/favicon-32x32.png">
13
- <link rel="icon" type="image/png" sizes="16x16" href="/1.13/assets/favicons/favicon-16x16.png">
14
- <link rel="manifest" href="/1.13/assets/favicons/site.webmanifest">
15
- <link rel="mask-icon" href="/1.13/assets/favicons/safari-pinned-tab.svg" color="#F86DA7">
16
- <link rel="shortcut icon" href="/1.13/assets/favicons/favicon.ico">
17
- <meta name="msapplication-TileColor" content="#F86DA7">
18
- <meta name="msapplication-config" content="/1.13/assets/favicons/browserconfig.xml">
19
- <meta name="theme-color" content="#F86DA7">
20
-
21
- <title>Graphiti</title>
22
- <meta name="description" content="Stylish Graph APIs">
23
-
24
- <link rel="stylesheet" href="/1.13/assets/main.css?ref=wh4t3v45">
25
- <link rel="alternate" type="application/rss+xml" title="Graphiti" href="/1.13/feed.xml">
26
-
27
- <!-- Global site tag (gtag.js) - Google Analytics -->
28
- <script async src="https://www.googletagmanager.com/gtag/js?id=UA-127904727-1"></script>
29
- <script>
30
- window.dataLayer = window.dataLayer || [];
31
- function gtag(){dataLayer.push(arguments);}
32
- gtag('js', new Date());
33
-
34
- gtag('config', 'UA-127904727-1');
35
- </script>
36
-
37
- <!-- javascript -->
38
- <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
39
- <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
40
-
41
-
42
- </head>
43
-
44
-
45
- <body>
46
- <main class="page-content" aria-label="Content">
47
- <div class="wrapper">
48
- <header class="navbar navbar-inverse normal" role="banner">
49
- <div class="container">
50
- <div class="navbar-header">
51
- <a href="/1.13/1.13" class="navbar-brand">
52
- <img alt="logo" src="/1.13/assets/img/logo.png">
53
- </a>
54
- </div>
55
- <nav class="" role="navigation">
56
- <ul class="nav navbar-nav nav-links">
57
- <li>
58
- <a class="quickstart nav-link" href="/1.13/quickstart">Quickstart</a>
59
- </li>
60
- <li>
61
- <a class="guides nav-link" href="/1.13/guides">Guides</a>
62
- </li>
63
- <li>
64
- <a class="tutorial nav-link" href="/1.13/tutorial">Tutorial</a>
65
- </li>
66
- <li>
67
- <a class="spraypaint nav-link" href="/1.13/js">Spraypaint</a>
68
- </li>
69
- </ul>
70
- <ul class="nav gh navbar-nav navbar-right visible-lg visible-md">
71
- <li>
72
- <span class="star">⭐</span>
73
- <a href="https://github.com/graphiti-api/graphiti">
74
- <img alt="github-star" style="margin-right: 65px;margin-top: -20px" src="/1.13/assets/img/gh.png">
75
- </a>
76
- </li>
77
- </ul>
78
- </nav>
79
- </div>
80
- </header>
81
-
82
- <div class="container">
83
- <div class="toc col-md-3">
84
- <h1 id="endpoints">Endpoints</h1>
85
-
86
- <ul>
87
- <li>1 <a href="#overview">Overview</a>
88
- <ul>
89
- <li><a href="#endpoint-logic">Endpoint logic</a></li>
90
- <li><a href="#rails-integration">Rails Integration</a></li>
91
- </ul>
92
- </li>
93
- <li>2 <a href="#customizing-resources">Customizing Resources</a>
94
- <ul>
95
- <li><a href="#scope-overrides">Scope Overrides</a></li>
96
- <li><a href="#sideload-allowlist">Sideload Allowlist</a></li>
97
- </ul>
98
- </li>
99
- <li>3 <a href="#caching">Caching</a>
100
- <ul>
101
- <li><a href="#etags">ETags</a></li>
102
- </ul>
103
- </li>
104
- <li>4 <a href="#testing">Testing</a></li>
105
- </ul>
106
-
107
- </div>
108
-
109
- <div class="col-md-8">
110
-
111
- <a class="anchor" id="overview" />
112
- <a class="header" href="#overview">
113
- <h2>
114
- 1 Overview
115
- </h2>
116
- </a>
117
-
118
- <p><strong>Endpoints</strong> expose and customize
119
- <a href="/1.13/guides/concepts/resources">Resources</a>.</p>
120
-
121
- <p>It’s important to remember that Resources themselves can operate
122
- completely independently of a request or response:</p>
123
-
124
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">employees</span> <span class="o">=</span> <span class="no">EmployeeResource</span><span class="p">.</span><span class="nf">all</span><span class="p">({</span>
125
- <span class="ss">filter: </span><span class="p">{</span> <span class="ss">title: </span><span class="s1">'engineer'</span> <span class="p">},</span>
126
- <span class="ss">sort: </span><span class="s1">'-created_at'</span><span class="p">,</span>
127
- <span class="ss">page: </span><span class="p">{</span> <span class="ss">size: </span><span class="mi">10</span> <span class="p">},</span>
128
- <span class="ss">include: </span><span class="s1">'positions.department'</span>
129
- <span class="p">})</span>
130
-
131
- <span class="n">employees</span><span class="p">.</span><span class="nf">map</span><span class="p">(</span><span class="o">&amp;</span><span class="ss">:first_name</span><span class="p">)</span> <span class="c1"># =&gt; ['Jane', 'John', ...]</span>
132
- <span class="n">employees</span><span class="p">.</span><span class="nf">to_json</span> <span class="c1"># =&gt; { employees: [{ ... }] }</span></code></pre></figure>
133
-
134
- <p>And Resources connect to other Resources. Our graph of data is defined
135
- <strong>outside</strong> of the actual API.</p>
136
-
137
- <p>Endpoints expose this graph to the world. We might choose to have a <code class="language-plaintext highlighter-rouge">/employees</code>
138
- endpoint that can eager load comments (<code class="language-plaintext highlighter-rouge">?include=comments</code>), but never expose
139
- <code class="language-plaintext highlighter-rouge">/comments</code> directly. Or, we could do the opposite: expose lazy-loading <code class="language-plaintext highlighter-rouge">/comments</code>,
140
- but disallow eager loading from <code class="language-plaintext highlighter-rouge">/employees</code>. We can add caching rules,
141
- or add an <code class="language-plaintext highlighter-rouge">/exemplary_employees</code> endpoint with special query overrides.</p>
142
-
143
- <p>Finally, Endpoints are in charge of the <a href="https://tools.ietf.org/html/rfc2616">HTTP specification</a>:
144
- request processing, response codes, caching, MIME types, and so on. If you’re thinking
145
- Rails, an Endpoint is the combination of a Route and Controller.</p>
146
-
147
- <a class="anchor" id="endpoint-logic" />
148
- <a class="header" href="#endpoint-logic">
149
- <h3>
150
- Endpoint Logic
151
- </h3>
152
- </a>
153
-
154
- <p>Often, you won’t need to customize Endpoints - especially if you’re
155
- using our <a href="/1.13/guides/concepts/resources#generators">Rails Resource
156
- generator</a>. Endpoint logic mostly
157
- concerns:</p>
158
-
159
- <ul>
160
- <li>Caching</li>
161
- <li>Side-effect behavior specific to the endpoint (e.g.: sending a
162
- welcome email from <code class="language-plaintext highlighter-rouge">/users#create</code> but not <code class="language-plaintext highlighter-rouge">/admin/users#create</code>)</li>
163
- <li>Authorization (e.g <code class="language-plaintext highlighter-rouge">before_action</code>)</li>
164
- <li>Custom query parameter handling</li>
165
- <li>Validation handling</li>
166
- <li>Error handling</li>
167
- <li>Limiting Resource behavior</li>
168
- <li>Customizing Resource behavior</li>
169
- </ul>
170
-
171
- <p>If your logic falls elsewhere, consider a Resource or Model.</p>
172
-
173
- <a class="anchor" id="rails-integration" />
174
- <a class="header" href="#rails-integration">
175
- <h3>
176
- 1.2 Rails Integration
177
- </h3>
178
- </a>
179
-
180
- <p>When using Rails, an endpoint is the combination of a Route and
181
- Controller:</p>
182
-
183
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># config/routes.rb</span>
184
- <span class="n">resources</span> <span class="ss">:posts</span><span class="p">,</span> <span class="ss">only: </span><span class="p">[</span><span class="ss">:index</span><span class="p">]</span>
185
-
186
- <span class="c1"># app/controllers/posts_controller.rb</span>
187
- <span class="k">class</span> <span class="nc">PostsController</span> <span class="o">&lt;</span> <span class="no">ApplicationController</span>
188
- <span class="k">def</span> <span class="nf">index</span>
189
- <span class="n">posts</span> <span class="o">=</span> <span class="no">PostResource</span><span class="p">.</span><span class="nf">all</span><span class="p">(</span><span class="n">params</span><span class="p">)</span>
190
- <span class="n">respond_with</span><span class="p">(</span><span class="n">posts</span><span class="p">)</span>
191
- <span class="k">end</span>
192
- <span class="k">end</span></code></pre></figure>
193
-
194
- <p>You’ll note that Graphiti hooks into Rails with a mixin (set when using
195
- our application generator):</p>
196
-
197
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">ApplicationController</span> <span class="o">&lt;</span> <span class="no">ActionController</span><span class="o">::</span><span class="no">API</span>
198
- <span class="kp">include</span> <span class="no">Graphiti</span><span class="o">::</span><span class="no">Rails</span>
199
-
200
- <span class="c1"># ... code ...</span>
201
- <span class="k">end</span></code></pre></figure>
202
-
203
- <p>This gives us <a href="#sideload-allowlist">#sideload_allowlist</a> and sets the
204
- <a href="/1.13/guides/concepts/resources#context">context</a>.</p>
205
-
206
- <a class="anchor" id="customizing-resources" />
207
- <a class="header" href="#customizing-resources">
208
- <h2>
209
- 2 Customizing Resources
210
- </h2>
211
- </a>
212
-
213
- <a class="anchor" id="scope-overrides" />
214
- <a class="header" href="#scope-overrides">
215
- <h3>
216
- Scope Overrides
217
- </h3>
218
- </a>
219
-
220
- <p>One common use case for endpoints is customizing the Resource
221
- <a href="/1.13/guides/concepts/resources#base-scope">base scope</a>. This causes a new
222
- “starting point” for query building.</p>
223
-
224
- <p>Consider the endpoints <code class="language-plaintext highlighter-rouge">/posts</code> (basic CRUD) and <code class="language-plaintext highlighter-rouge">/top_posts</code>. Though
225
- both are associated to PostResource, <code class="language-plaintext highlighter-rouge">/top_posts</code> ensures that only
226
- Posts with a certain number of upvotes get returned:</p>
227
-
228
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">index</span>
229
- <span class="n">base_scope</span> <span class="o">=</span> <span class="no">Post</span><span class="p">.</span><span class="nf">where</span><span class="p">(</span><span class="s2">"upvotes &gt; ?"</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
230
- <span class="n">posts</span> <span class="o">=</span> <span class="no">PostResource</span><span class="p">.</span><span class="nf">all</span><span class="p">(</span><span class="n">params</span><span class="p">,</span> <span class="n">base_scope</span><span class="p">)</span>
231
- <span class="n">respond_with</span><span class="p">(</span><span class="n">posts</span><span class="p">)</span>
232
- <span class="k">end</span></code></pre></figure>
233
-
234
- <p>We’re able to reuse all the other logic in PostResource - relationships,
235
- filters, sorts, etc - while only returning “Top Posts”.</p>
236
-
237
- <a class="anchor" id="sideload-allowlist" />
238
- <a class="header" href="#sideload-allowlist">
239
- <h3>
240
- Sideload Allowlist
241
- </h3>
242
- </a>
243
-
244
- <p>Resources define relationships to other resources. But we may not want
245
- all of those relationships exposed at a given endpoint.</p>
246
-
247
- <p>Let’s say we’ve defined relationships:</p>
248
-
249
- <p><code class="language-plaintext highlighter-rouge">Employee &gt; Position &gt; Department &gt; Hardware &gt; CostHistory</code></p>
250
-
251
- <p>It’s reasonable to get an Employee, their Positions, and Departments for
252
- those positions in a single request. But is it really valid to <em>also</em> pull down
253
- all the hardware, as well as all the historical data on the cost of that hardware,
254
- in a single request? Allowing the entire graph to be pulled down in a single request can cause excessive load on our
255
- servers (and this is probably a better fit for lazy-loading via
256
- <a href="/1.13/guides/concepts/links">Links</a>).</p>
257
-
258
- <p>Let’s instead say that if we’re entering the graph at <code class="language-plaintext highlighter-rouge">/employees</code>, the
259
- furthest we can go is Department:</p>
260
-
261
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">EmployeesController</span> <span class="o">&lt;</span> <span class="no">ApplicationController</span>
262
- <span class="nb">self</span><span class="p">.</span><span class="nf">sideload_allowlist</span> <span class="o">=</span> <span class="p">{</span>
263
- <span class="ss">index: </span><span class="p">{</span> <span class="ss">positions: </span><span class="s1">'department'</span> <span class="p">}</span>
264
- <span class="p">}</span>
265
-
266
- <span class="c1"># ... code ...</span>
267
- <span class="k">end</span></code></pre></figure>
268
-
269
- <a class="anchor" id="caching" />
270
- <a class="header" href="#caching">
271
- <h2>
272
- Caching
273
- </h2>
274
- </a>
275
-
276
- <a class="anchor" id="etags" />
277
- <a class="header" href="#etags">
278
- <h3>
279
- Etags
280
- </h3>
281
- </a>
282
-
283
- <p><a href="https://robots.thoughtbot.com/introduction-to-conditional-http-caching-with-rails">ETags</a> are an important concept that is often overlooked. Etags tell browsers
284
- that the response to a GET request hasn’t changed since the last request and
285
- can be safely pulled from the browser cache. If you care about sparse fieldsets,
286
- you should care about ETags - if you’re limiting fields to reduce payload size,
287
- how about a payload size of <strong>zero</strong>?</p>
288
-
289
- <p>It’s important to note that ETags are set by default in Rails, by
290
- checking the response body. This won’t prevent queries from executing,
291
- but it will save clients from downloading the response again if nothing
292
- has changed.</p>
293
-
294
- <p>Let’s manually set an ETag:</p>
295
-
296
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">index</span>
297
- <span class="n">posts</span> <span class="o">=</span> <span class="no">PostResource</span><span class="p">.</span><span class="nf">all</span><span class="p">(</span><span class="n">params</span><span class="p">)</span>
298
-
299
- <span class="k">if</span> <span class="n">stale?</span><span class="p">(</span><span class="n">posts</span><span class="p">.</span><span class="nf">data</span><span class="p">)</span>
300
- <span class="n">respond_with</span><span class="p">(</span><span class="n">posts</span><span class="p">)</span>
301
- <span class="k">end</span>
302
- <span class="k">end</span></code></pre></figure>
303
-
304
- <p>From the <a href="https://api.rubyonrails.org/v5.2.1/classes/ActionController/ConditionalGet.html#method-i-stale-3F">documentation on #stale?</a>:</p>
305
-
306
- <blockquote>
307
- <p><em>In this case last_modified will be set by calling <code class="language-plaintext highlighter-rouge">maximum(:updated_at)</code> on the collection (the timestamp of the most recently updated record) and the etag by passing the object itself.</em></p>
308
- </blockquote>
309
-
310
- <p>Also consider the use case where data is ingested hourly. We can avoid a
311
- query altogether by checking when the last ingestion ran:</p>
312
-
313
- <figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">index</span>
314
- <span class="k">if</span> <span class="n">stale?</span><span class="p">(</span><span class="no">EmployeeIngestion</span><span class="p">.</span><span class="nf">last</span><span class="p">)</span>
315
- <span class="n">employees</span> <span class="o">=</span> <span class="no">EmployeeResource</span><span class="p">.</span><span class="nf">all</span><span class="p">(</span><span class="n">params</span><span class="p">)</span>
316
- <span class="n">respond_with</span><span class="p">(</span><span class="n">employees</span><span class="p">)</span>
317
- <span class="k">end</span>
318
- <span class="k">end</span></code></pre></figure>
319
-
320
- <blockquote>
321
- <p><strong>CAVEAT</strong>: When setting ETags, consider sideloads. In the above examples
322
- we are checking to see the last update of an Employee, but we may be
323
- sideloading (and filtering) Positions as well. Use custom endpoints or
324
- <a href="#sideload-allowlist">Sideload Allowlist</a> to mitigate this issue.</p>
325
- </blockquote>
326
-
327
- <a class="anchor" id="testing" />
328
- <a class="header" href="#testing">
329
- <h2>
330
- 4 Testing
331
- </h2>
332
- </a>
333
-
334
- <p>If you have custom Endpoint logic, we suggest testing using an <a href="/1.13/guides/concepts/testing#api-tests">API
335
- Test</a>.</p>
336
- </div>
337
-
338
- </div>
339
- </div>
340
- </main>
341
- <div class="main-footer main-footer--dark">
342
- <div class="container">
343
- <div class="row">
344
- <div class="col-sm-4 menu">
345
- <h3>Overview</h3>
346
- <ul>
347
- <li>
348
- <a href="/1.13/quickstart">Quickstart</a>
349
- </li>
350
- <li>
351
- <a href="/1.13/tutorial">Tutorial</a>
352
- </li>
353
- <li>
354
- <a href="/1.13/guides">Guides</a>
355
- </li>
356
- </ul>
357
- </div>
358
- <div class="col-sm-4 menu">
359
- <h3>Contact</h3>
360
- <ul>
361
- <li>
362
- <a target="_blank" href="https://discord.gg/wgqkMBsSRV">Discord Chat</a>
363
- </li>
364
- <li>
365
- <a href="mailto:richmolj@gmail.com">Email</a>
366
- </li>
367
- </ul>
368
- </div>
369
- <div class="col-sm-4 menu">
370
- <h3>Related</h3>
371
- <ul>
372
- <li>
373
- <a target="_blank" href="http://jsonapi.org">JSONAPI Spec</a>
374
- </li>
375
- <li>
376
- <a target="_blank" href="http://jsonapi-rb.org">jsonapi-rb</a>
377
- </li>
378
- <li>
379
- <a target="_blank" href="https://vuejs.org/">VueJS</a>
380
- </li>
381
- </ul>
382
- </div>
383
- </div>
384
- </div>
385
- </div>
386
-
387
- <script type="text/javascript">
388
- $(function () {
389
-
390
- var flipTabs = function() {
391
- var isTS = true;
392
- if (localStorage.getItem('js-lang') === 'javascript') {
393
- isTS = false;
394
- }
395
-
396
- $('.code-tabs').each(function(index, el) {
397
- if (isTS) {
398
- console.log('hiding js');
399
- $($(el).children()[1]).hide();
400
- $($(el).children()[0]).show();
401
- } else {
402
- console.log('hiding ts');
403
- $($(el).children()[0]).hide();
404
- $($(el).children()[1]).show();
405
- }
406
- });
407
-
408
- if (isTS) {
409
- $('.tab.typescript').addClass('active');
410
- $('.tab.javascript').removeClass('active');
411
- } else {
412
- $('.tab.typescript').removeClass('active');
413
- $('.tab.javascript').addClass('active');
414
- }
415
- }
416
-
417
- $('.tab').click(function() {
418
- if ($(this).hasClass('typescript')) {
419
- localStorage.setItem('js-lang', 'typescript');
420
- } else {
421
- localStorage.setItem('js-lang', 'javascript');
422
- }
423
-
424
- flipTabs();
425
- });
426
-
427
- flipTabs();
428
- })
429
- </script>
430
-
431
- </body>
432
- </html>