graphiti 2.0.0.beta.7 → 2.0.0.beta.9

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 (251) hide show
  1. checksums.yaml +4 -4
  2. data/.git-blame-ignore-revs +2 -0
  3. data/.github/workflows/ci.yml +56 -4
  4. data/.github/workflows/docs.yml +10 -7
  5. data/.github/workflows/notify-example-app.yml +18 -0
  6. data/.github/workflows/release.yml +1 -1
  7. data/.gitignore +2 -0
  8. data/.standard.yml +6 -0
  9. data/CHANGELOG.md +66 -0
  10. data/CONTRIBUTING.md +3 -1
  11. data/README.md +13 -206
  12. data/Rakefile +34 -3
  13. data/UPGRADING.md +2 -2
  14. data/graphiti.gemspec +8 -4
  15. data/lib/generators/graphiti/generator_mixin.rb +1 -1
  16. data/lib/generators/graphiti/install_generator.rb +1 -1
  17. data/lib/generators/graphiti/resource_generator.rb +6 -3
  18. data/lib/generators/graphiti/templates/application_resource.rb.erb +19 -0
  19. data/lib/generators/graphiti/templates/controller.rb.erb +26 -8
  20. data/lib/graphiti/audit/report.rb +6 -6
  21. data/lib/graphiti/audit.rb +3 -4
  22. data/lib/graphiti/configuration.rb +11 -4
  23. data/lib/graphiti/debugger.rb +18 -6
  24. data/lib/graphiti/delegates/pagination.rb +2 -2
  25. data/lib/graphiti/deserializer.rb +3 -3
  26. data/lib/graphiti/error_serializers/deprecated_constants.rb +23 -0
  27. data/lib/graphiti/error_serializers/invalid_request.rb +6 -0
  28. data/lib/graphiti/errors.rb +22 -6
  29. data/lib/graphiti/extensions/temp_id.rb +1 -1
  30. data/lib/graphiti/query.rb +5 -4
  31. data/lib/graphiti/rails/context.rb +2 -1
  32. data/lib/graphiti/rails/controller.rb +3 -0
  33. data/lib/graphiti/rails/debugging.rb +1 -1
  34. data/lib/graphiti/rails/responders.rb +2 -1
  35. data/lib/graphiti/rails.rb +14 -0
  36. data/lib/graphiti/railtie.rb +8 -0
  37. data/lib/graphiti/resource/configuration.rb +1 -0
  38. data/lib/graphiti/resource/dsl.rb +2 -2
  39. data/lib/graphiti/resource/links.rb +1 -1
  40. data/lib/graphiti/resource/persistence.rb +1 -1
  41. data/lib/graphiti/resource/polymorphism.rb +1 -1
  42. data/lib/graphiti/resource.rb +2 -2
  43. data/lib/graphiti/resource_proxy.rb +0 -1
  44. data/lib/graphiti/scope.rb +68 -21
  45. data/lib/graphiti/scoping/filter.rb +5 -3
  46. data/lib/graphiti/scoping/paginate.rb +1 -1
  47. data/lib/graphiti/scoping/sort.rb +1 -1
  48. data/lib/graphiti/sideload/has_many.rb +1 -1
  49. data/lib/graphiti/sideload/polymorphic_belongs_to.rb +11 -4
  50. data/lib/graphiti/sideload.rb +8 -6
  51. data/lib/graphiti/spec_helpers/errors_proxy.rb +1 -1
  52. data/lib/graphiti/spec_helpers/matchers.rb +1 -1
  53. data/lib/graphiti/types.rb +5 -1
  54. data/lib/graphiti/util/cache_debug.rb +3 -3
  55. data/lib/graphiti/util/hash.rb +1 -1
  56. data/lib/graphiti/util/persistence.rb +6 -6
  57. data/lib/graphiti/util/serializer_relationships.rb +11 -2
  58. data/lib/graphiti/version.rb +1 -1
  59. data/lib/graphiti.rb +1 -1
  60. data/lib/tasks/graphiti.rake +1 -1
  61. data/package-lock.json +114 -0
  62. data/package.json +16 -3
  63. metadata +33 -198
  64. data/docs/concepts/backends-and-models.md +0 -122
  65. data/docs/concepts/endpoints.md +0 -183
  66. data/docs/concepts/links.md +0 -212
  67. data/docs/concepts/overview.md +0 -80
  68. data/docs/concepts/persisting.md +0 -376
  69. data/docs/concepts/relationships.md +0 -627
  70. data/docs/concepts/resources.md +0 -677
  71. data/docs/getting-started/first-api.md +0 -289
  72. data/docs/getting-started/installation.md +0 -185
  73. data/docs/intro.md +0 -307
  74. data/docs/js/authentication.md +0 -63
  75. data/docs/js/ddau.md +0 -20
  76. data/docs/js/extra-params.md +0 -41
  77. data/docs/js/index.md +0 -112
  78. data/docs/js/installation.md +0 -120
  79. data/docs/js/middleware.md +0 -72
  80. data/docs/js/models.md +0 -202
  81. data/docs/js/reads.md +0 -494
  82. data/docs/js/state-syncing.md +0 -100
  83. data/docs/js/writes.md +0 -373
  84. data/docs/reference/vandal.md +0 -63
  85. data/docs/reference/why.md +0 -13
  86. data/docs/topics/authorization.md +0 -155
  87. data/docs/topics/caching.md +0 -55
  88. data/docs/topics/customizing-sideloads.md +0 -156
  89. data/docs/topics/debugging.md +0 -242
  90. data/docs/topics/error-handling.md +0 -210
  91. data/docs/topics/etags.md +0 -46
  92. data/docs/topics/hopping-relationships.md +0 -149
  93. data/docs/topics/json-attributes.md +0 -77
  94. data/docs/topics/openstruct-models.md +0 -50
  95. data/docs/topics/remote-resources.md +0 -291
  96. data/docs/topics/testing.md +0 -916
  97. data/docs/topics/without-activerecord.md +0 -324
  98. data/docs/tutorial/index.md +0 -58
  99. data/docs/tutorial/step_0.md +0 -107
  100. data/docs/tutorial/step_1.md +0 -199
  101. data/docs/tutorial/step_2.md +0 -312
  102. data/docs/tutorial/step_3.md +0 -142
  103. data/docs/tutorial/step_4.md +0 -135
  104. data/docs/tutorial/step_5.md +0 -69
  105. data/docs/tutorial/step_6.md +0 -82
  106. data/docs/tutorial/step_7.md +0 -205
  107. data/docs/tutorial/step_8.md +0 -128
  108. data/docs/tutorial/step_9.md +0 -171
  109. data/docs/upgrading.md +0 -267
  110. data/website/.gitignore +0 -20
  111. data/website/README.md +0 -43
  112. data/website/docusaurus.config.js +0 -197
  113. data/website/package-lock.json +0 -19474
  114. data/website/package.json +0 -46
  115. data/website/sidebars.js +0 -82
  116. data/website/src/css/custom.css +0 -85
  117. data/website/src/pages/markdown-page.mdx +0 -7
  118. data/website/static/.nojekyll +0 -0
  119. data/website/static/1.13/2019/03/31/graphiti-1-0.html +0 -205
  120. data/website/static/1.13/2019/05/08/graphiti-1-1.html +0 -212
  121. data/website/static/1.13/2019/05/20/graphiti-1-2.html +0 -214
  122. data/website/static/1.13/2019/10/14/tutorial.html +0 -198
  123. data/website/static/1.13/CNAME +0 -1
  124. data/website/static/1.13/README.md +0 -16
  125. data/website/static/1.13/assets/css/syntax.css +0 -60
  126. data/website/static/1.13/assets/favicons/android-chrome-192x192.png +0 -0
  127. data/website/static/1.13/assets/favicons/android-chrome-256x256.png +0 -0
  128. data/website/static/1.13/assets/favicons/apple-touch-icon.png +0 -0
  129. data/website/static/1.13/assets/favicons/browserconfig.xml +0 -9
  130. data/website/static/1.13/assets/favicons/favicon-16x16.png +0 -0
  131. data/website/static/1.13/assets/favicons/favicon-32x32.png +0 -0
  132. data/website/static/1.13/assets/favicons/favicon.ico +0 -0
  133. data/website/static/1.13/assets/favicons/mstile-150x150.png +0 -0
  134. data/website/static/1.13/assets/favicons/safari-pinned-tab.svg +0 -1
  135. data/website/static/1.13/assets/favicons/site.webmanifest +0 -19
  136. data/website/static/1.13/assets/img/backend.gif +0 -0
  137. data/website/static/1.13/assets/img/conformity.png +0 -0
  138. data/website/static/1.13/assets/img/error_payload.png +0 -0
  139. data/website/static/1.13/assets/img/fancy-cushion.png +0 -0
  140. data/website/static/1.13/assets/img/gh.png +0 -0
  141. data/website/static/1.13/assets/img/home-bg.jpg +0 -0
  142. data/website/static/1.13/assets/img/lifecycle.gif +0 -0
  143. data/website/static/1.13/assets/img/logo-500.png +0 -0
  144. data/website/static/1.13/assets/img/logo.png +0 -0
  145. data/website/static/1.13/assets/img/love-graffiti.jpg +0 -0
  146. data/website/static/1.13/assets/img/meta_total_count.png +0 -0
  147. data/website/static/1.13/assets/img/persist.jpg +0 -0
  148. data/website/static/1.13/assets/img/resource.gif +0 -0
  149. data/website/static/1.13/assets/img/rest-graffiti.jpg +0 -0
  150. data/website/static/1.13/assets/img/rest1.gif +0 -0
  151. data/website/static/1.13/assets/img/rest2.gif +0 -0
  152. data/website/static/1.13/assets/img/rest3.gif +0 -0
  153. data/website/static/1.13/assets/img/rethink-rest-graffiti.jpg +0 -0
  154. data/website/static/1.13/assets/img/sunrise.png +0 -0
  155. data/website/static/1.13/assets/img/why.png +0 -0
  156. data/website/static/1.13/assets/js/highlight.pack.js +0 -2
  157. data/website/static/1.13/assets/main.css +0 -15518
  158. data/website/static/1.13/assets/main.css.map +0 -1
  159. data/website/static/1.13/bin/bundle +0 -109
  160. data/website/static/1.13/bin/jekyll +0 -27
  161. data/website/static/1.13/bin/kramdown +0 -27
  162. data/website/static/1.13/bin/listen +0 -27
  163. data/website/static/1.13/bin/rake +0 -27
  164. data/website/static/1.13/bin/rougify +0 -27
  165. data/website/static/1.13/bin/safe_yaml +0 -27
  166. data/website/static/1.13/bin/sass +0 -27
  167. data/website/static/1.13/bin/sass-convert +0 -27
  168. data/website/static/1.13/bin/scss +0 -27
  169. data/website/static/1.13/blog.html +0 -259
  170. data/website/static/1.13/cheatsheet.html +0 -316
  171. data/website/static/1.13/cookbooks/authorization.md +0 -0
  172. data/website/static/1.13/cookbooks/caching.md +0 -0
  173. data/website/static/1.13/cookbooks/customizing-sideloads.html +0 -325
  174. data/website/static/1.13/cookbooks/etags.md +0 -0
  175. data/website/static/1.13/cookbooks/hopping-relationships.html +0 -324
  176. data/website/static/1.13/cookbooks/json_attributes.md +0 -0
  177. data/website/static/1.13/cookbooks/openstruct-models.md +0 -0
  178. data/website/static/1.13/cookbooks/remote-resources.md +0 -0
  179. data/website/static/1.13/cookbooks/without-activerecord.html +0 -510
  180. data/website/static/1.13/features.html +0 -249
  181. data/website/static/1.13/feed.xml +0 -106
  182. data/website/static/1.13/guides/concepts/backends-and-models.html +0 -467
  183. data/website/static/1.13/guides/concepts/debugging.html +0 -440
  184. data/website/static/1.13/guides/concepts/endpoints.html +0 -432
  185. data/website/static/1.13/guides/concepts/error-handling.html +0 -396
  186. data/website/static/1.13/guides/concepts/links.html +0 -501
  187. data/website/static/1.13/guides/concepts/remote-resources.html +0 -536
  188. data/website/static/1.13/guides/concepts/resources.html +0 -2176
  189. data/website/static/1.13/guides/concepts/testing.html +0 -1469
  190. data/website/static/1.13/guides/getting-started/installation.html +0 -420
  191. data/website/static/1.13/guides/graphiti-rails-migration.html +0 -242
  192. data/website/static/1.13/guides/index.html +0 -269
  193. data/website/static/1.13/guides/overview.html +0 -325
  194. data/website/static/1.13/guides/upgrading-2-0.html +0 -193
  195. data/website/static/1.13/guides/upgrading.html +0 -314
  196. data/website/static/1.13/guides/vandal.html +0 -282
  197. data/website/static/1.13/guides/why.html +0 -1121
  198. data/website/static/1.13/index.html +0 -72
  199. data/website/static/1.13/js/authentication.html +0 -295
  200. data/website/static/1.13/js/ddau.html +0 -238
  201. data/website/static/1.13/js/extra-params.html +0 -270
  202. data/website/static/1.13/js/index.html +0 -321
  203. data/website/static/1.13/js/installation.html +0 -637
  204. data/website/static/1.13/js/introduction.html +0 -257
  205. data/website/static/1.13/js/middleware.html +0 -318
  206. data/website/static/1.13/js/reads/fieldsets.html +0 -271
  207. data/website/static/1.13/js/reads/filtering.html +0 -289
  208. data/website/static/1.13/js/reads/includes.html +0 -260
  209. data/website/static/1.13/js/reads/index.html +0 -497
  210. data/website/static/1.13/js/reads/nested-queries.html +0 -353
  211. data/website/static/1.13/js/reads/pagination.html +0 -260
  212. data/website/static/1.13/js/reads/sorting.html +0 -265
  213. data/website/static/1.13/js/reads/statistics.html +0 -289
  214. data/website/static/1.13/js/state-syncing.html +0 -340
  215. data/website/static/1.13/js/writes/deferred.html +0 -296
  216. data/website/static/1.13/js/writes/dirty-tracking.html +0 -399
  217. data/website/static/1.13/js/writes/index.html +0 -391
  218. data/website/static/1.13/js/writes/nested.html +0 -330
  219. data/website/static/1.13/js/writes/validations.html +0 -272
  220. data/website/static/1.13/quickstart.html +0 -660
  221. data/website/static/1.13/template +0 -161
  222. data/website/static/1.13/tutorial/index.html +0 -250
  223. data/website/static/1.13/tutorial/step_0.html +0 -292
  224. data/website/static/1.13/tutorial/step_1.html +0 -517
  225. data/website/static/1.13/tutorial/step_2.html +0 -481
  226. data/website/static/1.13/tutorial/step_3.html +0 -323
  227. data/website/static/1.13/tutorial/step_4.html +0 -318
  228. data/website/static/1.13/tutorial/step_5.html +0 -265
  229. data/website/static/1.13/tutorial/step_6.html +0 -276
  230. data/website/static/1.13/tutorial/step_7.html +0 -390
  231. data/website/static/1.13/tutorial/step_8.html +0 -316
  232. data/website/static/1.13/tutorial/step_9.html +0 -365
  233. data/website/static/CNAME +0 -1
  234. data/website/static/assets/img/error_payload.png +0 -0
  235. data/website/static/assets/img/legacy/legacy-0378a3bb39.png +0 -0
  236. data/website/static/assets/img/legacy/legacy-05bbd3e5fd.png +0 -0
  237. data/website/static/assets/img/legacy/legacy-07aa104495.png +0 -0
  238. data/website/static/assets/img/legacy/legacy-0c75a16b3a.gif +0 -0
  239. data/website/static/assets/img/legacy/legacy-3076df6209.png +0 -0
  240. data/website/static/assets/img/legacy/legacy-7f6889bc89.png +0 -0
  241. data/website/static/assets/img/legacy/legacy-a2cc4363c3.png +0 -0
  242. data/website/static/assets/img/legacy/legacy-f67cfa89ab.png +0 -0
  243. data/website/static/assets/img/meta_total_count.png +0 -0
  244. data/website/static/img/docusaurus-social-card.jpg +0 -0
  245. data/website/static/img/docusaurus.png +0 -0
  246. data/website/static/img/favicon.ico +0 -0
  247. data/website/static/img/logo.png +0 -0
  248. data/website/static/img/logo.svg +0 -1
  249. data/website/static/img/undraw_docusaurus_mountain.svg +0 -171
  250. data/website/static/img/undraw_docusaurus_react.svg +0 -170
  251. 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>