graphiti 2.0.0.beta.2 → 2.0.0.beta.4

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