-
Notifications
You must be signed in to change notification settings - Fork 0
/
case-study.html
2190 lines (1983 loc) · 96.9 KB
/
case-study.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html data-wf-page="5f71dd169010d6326b65485d">
<head>
<meta charset="utf-8" />
<title>Synapse • Case Study</title>
<meta content="width=device-width, initial-scale=1" name="viewport" />
<link href="assets/css/style.css" rel="stylesheet" type="text/css" />
<script
src="https://ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js"
type="text/javascript"
></script>
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Inter:regular,500,600,700"
media="all"
/>
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Work+Sans"
/>
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Nunito+Sans"
/>
<meta
name="image"
property="og:image"
content="assets/images/synapse-case-study.png"
/>
<script type="text/javascript">
WebFont.load({ google: { families: ["Inter:regular,500,600,700"] } });
</script>
<script type="text/javascript">
!(function (o, c) {
var n = c.documentElement,
t = " w-mod-";
(n.className += t + "js"),
("ontouchstart" in o ||
(o.DocumentTouch && c instanceof DocumentTouch)) &&
(n.className += t + "touch");
})(window, document);
</script>
<link
href="assets/images/logo-mono.png"
rel="shortcut icon"
type="image/x-icon"
/>
<link href="assets/images/logo-mono.png" rel="apple-touch-icon" />
<script
src="https://kit.fontawesome.com/d019875f94.js"
crossorigin="anonymous"
></script>
<meta
name="image"
property="og:image"
content="assets/images/thumbnail.png"
/>
</head>
<body>
<!--Navbar-->
<div class="navigation-wrap" id="navbar">
<div
data-collapse="medium"
data-animation="default"
data-duration="400"
role="banner"
class="navigation w-nav"
>
<div class="navigation-container">
<div class="navigation-left">
<a
href="/"
aria-current="page"
class="brand w-nav-brand w--current"
aria-label="home"
>
<img
src="assets/images/logo-color.png"
alt=""
class="template-logo"
onmouseover="hover(this);"
onmouseout="unhover(this);"
/>
</a>
<nav role="navigation" class="nav-menu w-nav-menu">
<a href="/case-study" class="link-block w-inline-block">
<div>Case Study</div>
</a>
<a href="/team" class="link-block w-inline-block">
<div>Team</div>
</a>
</nav>
</div>
<div class="navigation-right">
<div class="login-buttons">
<a
href="https://github.com/synapse-gateway/synapse-builder"
target="_blank"
>
<span style="color: #0a0188">
<i class="fab fa-github fa-lg"></i>
</span>
</a>
</div>
</div>
</div>
<div class="w-nav-overlay" data-wf-ignore="" id="w-nav-overlay-0"></div>
</div>
</div>
<!-- <div class="wrapper"></div> -->
<div id="sidebar" class="toc"></div>
<div class="section header">
<article class="container case-study-container">
<div class="hero-text-container">
<h1 class="h1 centered">Case Study</h1>
</div>
<div id="case-study">
<br />
<br />
<!-- Section 1 -->
<div class="case-study-section">
<div class="case-study-subsection">
<h2 class="h2">1. Introduction</h2>
<p>
We have seen a huge shift in computing architecture over the past
decade, with engineers opting to modularize and distribute their
services to remain agile. This approach enables quick integration
and iteration over the traditional monolithic approach to system
design. But by distributing services over the network, we trade this
development agility for processing time, as we accrue latency by
increasing the number of requests made over the network to the
various services.
</p>
<p>
The latency problem is made worse by the inflexibility of
traditional API technologies. Although new approaches to API design
have emerged to address some of these issues, adoption of these
alternatives typically requires a complete redesign of each service.
</p>
</div>
<div class="case-study-subsection">
<h3>1.1 What is Synapse?</h3>
<p>
Synapse is an open-source solution for building, deploying, and
monitoring a GraphQL Gateway. Synapse enables you to put your legacy
APIs behind a single GraphQL endpoint. It allows teams to easily
deploy a new GraphQL Gateway onto AWS infrastructure and
monitor requests made to the gateway.
</p>
<p>
Synapse abstracts away the complex issues involved in adopting GraphQL by putting your
legacy backend services behind a GraphQL API gateway with a single
endpoint for client access. Developers are able to use a GUI to
configure the GraphQL gateway to include a wide variety of data sources such as REST, OpenAPI, JSON Schema, and GraphQL endpoints or databases like MongoDB and Postgres.
</p>
<p>
Our case study will examine why and how we designed and created
Synapse. Our main goal was to create a relatively easy way to turn a
complex microservice infrastructure into a single GraphQL API and
deploy it to AWS efficiently. There were many challenges we faced in
doing so and this case study will explain how we solved those
difficulties and why we made the choices we did.
</p>
<p>
First, we will explain the general web application infrastructure
and some of the problems it can present to modern day applications.
</p>
</div>
<div class="case-study-subsection">
<h3>1.2 Monolithic Application Architecture</h3>
<p>
Traditionally, applications have been designed as and often start
out as monolithic applications, meaning that while the software may
have many different components, it is usually contained on one
server and tightly coupled, or interconnected, together. The
benefits of this type of architecture is that it is fairly simple to
develop, test, and deploy. It can scale up fairly well simply by
creating new instances of the application as needed behind a tool
such as a load balancer.
</p>
<figure>
<img
src="assets/images/case-study/monolith-diagram.png"
class="case-study-image shrink"
/>
<figcaption>Fig. 1: Example Monolithic Architecture</figcaption>
</figure>
<p>
However, the drawbacks of this architectural style become evident as
the application gets more complex and grows ever larger. Several
problems include:
</p>
<ol>
<li>Size of the application can slow start up time</li>
<li>
Changing one part of the code can have an unanticipated ripple
effect elsewhere in the application
</li>
<li>
Reliability issues - a bug in any part could bring down the entire
application
</li>
<li>Barrier to adopting new technologies</li>
<li>Must redeploy entire application if there is an update</li>
</ol>
<p>
These problems can lead to the adoption of what is known as a
microservices architecture.
</p>
</div>
<div class="case-study-subsection">
<h3>1.3 Microservices Architecture</h3>
<p>
Instead of one, tightly coupled application, different services are
split into self-contained, loosely coupled microservices. Each
microservice is usually a small application unto itself that exposes
its own API for use by the other services and relies on its own
separate database if needed.
</p>
<figure>
<img
src="assets/images/case-study/microservice-diagram.png"
class="case-study-image shrink"
style="max-width: 400px;"
/>
<figcaption>Fig. 2: Example Microservices Architecture</figcaption>
</figure>
<p>The main benefits of a microservices architecture include:</p>
<ol>
<li>
Less complex application since each service can be managed
independently of the others
</li>
<li>
Each service can be developed independently by a team just focused
on that service
</li>
<li>Enables continuous deployment</li>
<li>Each service can be scaled independently</li>
<li>
Developers are not bound to a specific technology for all services
</li>
</ol>
<p>
One main tool that is often necessitated by a microservices
architecture is an API gateway. Since there is no longer just one
service containing all parts of the application,
this gateway is responsible for routing all incoming requests to the
proper service and providing the response.
</p>
</div>
<div class="case-study-subsection">
<h3>1.4 What is an API?</h3>
<p>
An Application Programming Interface (API) provides a specification
for applications and devices to communicate with each other. For
example, an API is what allows one computer to get information from
a server or even another device. There are many ways to design and
build an API, as well as different specifications to use such as
OpenAPI, REST, JSON Schema, RPC and others.
</p>
</div>
<div class="case-study-subsection">
<h3>1.5 REST APIs</h3>
<p>
One of the most common patterns for API design is REST. When one REST API endpoint does not return all the data that is
needed to fulfill the request, this results in under-fetching as the
client still requires more data from another endpoint, causing
additional network requests.
</p>
<p>
Over-fetching data may also occur and slow transmission speed when a
response contains more data than what is actually needed due to the
nature of what the REST endpoint is programmed to return.
</p>
<p>
Below is an example request to get all of a specific user’s posts
and display them with the user name who created the post. To obtain
this data we will actually need to make two separate requests. This
is because one request to the user/id endpoint does not get all the
data that is required.
</p>
<figure>
<img
src="assets/images/case-study/rest-workflow.png"
class="case-study-image enlarge"
/>
<figcaption>
Fig. 3: An example of a GET Request to /users/id
</figcaption>
</figure>
<p>
This example illustrates two problems that can occur when
interacting with a REST API. First, one request to the user/id
endpoint does not get all the data that is required and thus
under-fetches what we need.
</p>
<p>
This also shows the over-fetching problem caused by REST APIs where
we only need the user name but are getting a response that also
includes the user address and birthday.
</p>
<p>
Below we see the second network request to a different API endpoint
that is needed to fulfill the client’s main request for all posts
from a specific user. As you can see, this also over-fetches more
data than what the client is asking for by providing comments as
well. Perhaps the client only wanted the title of the posts but is
getting back the content also.
</p>
<figure>
<img
src="assets/images/case-study/rest-workflow2.png"
class="case-study-image enlarge"
/>
<figcaption>
Fig. 4: An example of a second GET Request to /users/id/posts
</figcaption>
</figure>
<p>
Being unable to obtain all the data the client needs in one network
request leads to multiple requests and slower response time from an
application. So what changes could be made to reduce the number of
network requests and improve the performance of a mobile app?
</p>
<p>
First, the developer could redesign all of their API endpoints to
meet the current demands of their clients. However, client demands
change and this would require a huge amount of overhaul of their
current systems.
</p>
<p>
Second, the developer could continue to create new API endpoints for
specific and often-requested data. This would eventually lead to an
immense API back-end that is constantly growing and trying to keep
up with changing client needs.
</p>
<p>
Third, the developer could choose to move away from REST patterns and use GraphQL, a query language developed to address exactly these issues.
</p>
</div>
</div>
<!-- Section 2 -->
<div class="case-study-section">
<div class="case-study-subsection">
<h2>2. Advent of GraphQL</h2>
<p>
The inflexibility of traditional API technologies led to the
development of GraphQL. GraphQL is a strongly-typed query language
for APIs developed by Facebook in 2012 to improve the performance of
their mobile applications by defining a specification that reduced
the need to prepare data on the server and parse it on the client’s
end. It allows the client to request and receive exactly the data
that is needed, no less, no more.
</p>
<p>
Despite being a more recently developed specification, GraphQL has
quickly become adopted throughout the industry since being released
by Facebook in 2015. According to the 2021 State of Javascript
Report, the percentage of developers using GraphQL has risen from 6%
in 2016 to 47% in 2021 topping the charts with a 94% developer
satisfaction rating. Also, over 84% of developers are either
interested in learning GraphQL or would definitely use it again.
</p>
</div>
<div class="case-study-subsection">
<h3>2.1 What is GraphQL?</h3>
<p>
With GraphQL, the underlying available data is organized by a
schema. The schema creates a hierarchy of type definitions, which
typically represent objects. Type definitions have one or more
fields, which indicates the return type of the data.
</p>
<figure>
<img
src="assets/images/case-study/schema.png"
class="case-study-image"
/>
<figcaption>Fig. 5: Example GraphQL API Schema</figcaption>
</figure>
<p>
This structure and strict type system means that we can query the
schema to see the data available for querying, as well as how return
objects may be structured. It also allows us to declare exactly
which fields from a returned type are needed, meaning the client
won’t overfetch from the application.
</p>
<figure>
<img
src="assets/images/case-study/query.png"
class="case-study-image"
/>
<figcaption>Fig. 6: Example GraphQL Query</figcaption>
</figure>
<p>
And lastly, the GraphQL specification allows us to perform multiple
queries in one request, even if the return types are independent,
solving the under-fetching issues and preventing the need for
multiple round-trips.
</p>
<figure>
<img
src="assets/images/case-study/response.png"
class="case-study-image"
/>
<figcaption>Fig. 7: Example GraphQL Response</figcaption>
</figure>
<p>
Here is an example of a feature of GraphQL that allows nested
queries and therefore requires only one client network request to
obtain data from various resources-this prevents both under and
over-fetching. Books are related to an author, we are querying for
the authors and then sub-querying their books. Since the books are
not a scalar type but a custom type, we need to specify which of
their properties must be retrieved.
</p>
<figure>
<img
src="assets/images/case-study/nested-response.png"
class="case-study-image enlarge"
/>
<figcaption>
Fig. 8: Example GraphQL Nested Query and Response
</figcaption>
</figure>
<p>In summary, the main benefits of GraphQL include:</p>
<ol>
<li>
The client can customize queries to fetch the exact data that is
needed when they need it
</li>
<li>It reduces the over and under-fetching of data</li>
<li>
It reduces the number of calls made over the network by the client
to the API
</li>
<li>
GraphQL provides a unified and optimized public API of services
reachable through a single endpoint.
</li>
</ol>
</div>
<div class="case-study-subsection">
<h3>2.2 Switching to a GraphQL API</h3>
<p>
From an existing API that is composed of many different endpoints,
how can a company switch to GraphQL? One approach would be to change
all of the current service endpoints into GraphQL. However this
would require a significant investment of time and money, as well as
a complete redesign of all service APIs to the GraphQL format.
</p>
<p>
Another common problem that would likely have to be addressed is
that some of the service APIs used by the company may in fact be
owned by third parties, such as a payment processor or email
service. These would not be available for the developer to change in
any way and have to be accessed in their current API format.
</p>
<p>Another option would be to use a GraphQL server.</p>
</div>
<div class="case-study-subsection">
<h3>2.3 Using a GraphQL Server</h3>
<p>
When we use a GraphQL server, the client can now simply make one
request to a single endpoint for the service, reducing the need for
multiple network requests from the client to the server. The GraphQL
server uses resolver functions to access the data source and return the requested
data.
</p>
<figure>
<img
src="assets/images/case-study/graphql-infront-rest.png"
class="case-study-image shrink"
/>
<figcaption>Fig. 9: Example GraphQL Server</figcaption>
</figure>
<p>However, the company may have several issues to deal with:</p>
<ul>
<li>How can we integrate existing APIs without needing to redesign each one?</li>
<li>How can we interact with different API types like REST, Open API, JSON schema, or even databases like MongoDB or SQL?</li>
<li>How do we integrate third-party APIs that we cannot change?</li>
<li>
How can we use GraphQL if our engineers have very little experience with it?
</li>
</ul>
<p>
To address these challenges, we can use a GraphQL API Gateway to
access all our backend services with one request.
</p>
</div>
<div class="case-study-subsection">
<h3>2.4 GraphQL API Gateway</h3>
<p>
In the configuration without a gateway, you can see in the diagram
below that the client still has to make multiple trips to different
graphql servers to access each service endpoint. However, when we
use a GraphQL gateway, the client can now simply make one request to
a single endpoint, reducing the need for multiple network requests
from the client to the server.
</p>
<figure>
<img
src="assets/images/case-study/gateway-animation.gif"
class="case-study-image"
/>
<figcaption>
Fig. 10: A transition from individual servers to a GraphQL gateway
</figcaption>
</figure>
<p>
A GraphQL server can functionally act as an API Gateway for
underlying data sources. Each underlying data source would have a
corresponding schema (subschema) that describes what data can be
queried from that specific source. Non-GraphQL APIs would require
resolver functions that expose this subschema - and we’ll talk more
about resolvers later.
</p>
<p>
The GraphQL gateway will aggregate these schemas into a single
schema which the client/service can now query as a single endpoint.
This solves the problem of under-fetching because all underlying
APIs are now accessible via a single client request.
</p>
</div>
<div class="case-study-subsection">
<h3>2.5 Benefits of Using a GraphQL API Gateway</h3>
<p>
In summary, the benefits of using a GraphQL API Gateway include:
</p>
<ol>
<li>Having one single endpoint to query and access all data</li>
<li>
Reducing under and over-fetching of resources from the client’s
perspective. The client can customize queries to only grab exactly
the data it needs. This is very helpful for improving the speed
and efficiency of mobile applications while reducing the number of
network requests.
</li>
<li>
A final benefit is that the gate provides a reduced attack surface
in terms of security. The focus can be enforcing security at the
gateway level rather than at each service’s API
</li>
</ol>
<p>
We now need to consider the best way to actually create an API
gateway using GraphQL and how Synapse can make doing so a smooth and
simple task.
</p>
</div>
</div>
<!-- Section 3 -->
<div class="case-study-section">
<div class="case-study-subsection">
<h2>3. Creating a GraphQL Gateway</h2>
<p>
There are two possible ways to create a GraphQL Gateway: Schema
stitching and Schema Federation.
</p>
</div>
<div class="case-study-subsection">
<h3>3.1 Schema Federation</h3>
<p>
To imagine how federation works it is helpful to think of one’s
underlying services as puzzle pieces. As seen in Figure 11, each
piece would be aware and designed to potentially fit together with
the others. From this, one can see that federation assumes a
company’s schema should be a distributed responsibility.
</p>
<figure>
<img
src="assets/images/case-study/federation-animation.gif"
class="case-study-image"
/>
<figcaption>
Fig. 11: Federation Puzzle Piece Analogy to combine service
schemas
</figcaption>
</figure>
<p>
To implement federation, underlying services need to be aware of
each other’s data and contain all of the logic for communicating
with one another to enable interwoven schemas, which allows for
nesting data across multiple services. Since the logic resides
within the services, the gateway acts as a thin layer responsible
for combining requested data and is able to be configured
automatically by reading the schemas of each underlying service.
</p>
</div>
<div class="case-study-subsection">
<h3>3.2 Schema Stitching</h3>
<p>
To imagine how stitching works, it is helpful to think of one’s
underlying services as individual pieces of fabric. As seen in
Figure 12, the pieces of fabric are completely separate and have no
knowledge they could potentially be stitched together. The gateway
acts as the seamstress, orchestrating the combining of the pieces
into one seamless schema. For this reason, stitching assumes a
company’s schema should be a centralized responsibility.
</p>
<figure>
<img
src="assets/images/case-study/stitching-animation.gif"
class="case-study-image"
/>
<figcaption>Fig. 12: Stitching Pieces of Fabric Analogy</figcaption>
</figure>
<p>
In stitching’s implementation, underlying services are unaware of
each other, meaning they are able to be left unaltered. The gateway
is what contains all the logic for combining services.
</p>
</div>
<div class="case-study-subsection">
<h3>3.3 Stitching vs. Federation</h3>
<p>
To determine which method is best for our purpose, we need to
compare the advantages and disadvantages of stitching and
federation.
</p>
<p>
Federation allows for faster development since new changes don’t
require full coordination with other services, allowing teams to
work on different services in parallel. Additionally, federation
needs a much “thinner” Gateway layer. Since the logic for combining
services is within the services themselves, the Gateway does not
contain much logic and can be considered less of a critical piece of
architecture.
</p>
<p>
However, both of these advantages come at a cost. Federation
requires developers to alter their underlying services to contain
the logic for combining them together. Not only does this alter the
services, but requires a high learning curve for the federation
specification, which is needed to add the logic. Additionally, by
linking the services together at the service layer, each service
becomes more tightly coupled to each other.
</p>
<p>
Stitching, on the other hand, allows underlying services to be
unaltered and uncoupled from each other, as all the logic resides in
the Gateway. Each service can remain the same stand-alone service it
was before the Gateway was introduced, needing no additional logic.
Additionally, the logic in the Gateway is written in the pure
GraphQL specification, rather than using the federation
specification, which can be thought of as its own language. This
significantly lowers the learning curve to adopting a GraphQL
Gateway.
</p>
<p>
However, stitching also has some disadvantages. Since all of the
logic resides in the gateway, the gateway now becomes a much more
critical piece of architecture. Additionally, stitching results in
an increase in coordination between teams. This is because any time
a new feature is released by a team, they must make sure the feature
won’t produce a breaking change to the gateway.
</p>
<p>
Synapse uses a schema stitching solution since one
of the primary aims of our tool was to lower the skill curve of
adopting GraphQL and allowing underlying services to remain
unaltered. Let’s investigate deeper into what Synapse is.
</p>
</div>
</div>
<!-- Section 4 -->
<div class="case-study-section">
<div class="case-study-subsection">
<h2 class="h2">4. Overview of Synapse</h2>
<figure>
<img
src="assets/images/case-study/synapse-overview.png"
class="case-study-image"
/>
<figcaption>Fig. 13: Synapse is a GraphQL Gateway</figcaption>
</figure>
<p>
As seen in Figure 13, Synapse is a GraphQL API Gateway solution,
which creates and deploys a GraphQL server, allowing users to
connect various types of different legacy APIs and data sources
using GraphQL and resulting in a single endpoint for clients to
query.
</p>
<p>
The primary goal behind Synapse was to provide an intuitive way to
unify legacy APIs into a single GraphQL endpoint. Additionally, our
team wanted to include some extra features, inspired by some other
GraphQL API Gateway solutions, which would make Synapse easy to use for a wide range of engineers.
</p>
<p>
First, our team aimed to have a simple and intuitive way to
configure the GraphQL Gateway. Synapse provides an intuitive GUI
interface to allow the developer to easily add their existing APIs
and data sources to the Gateway. This eliminated the need to add and
modify configuration files manually in a backend directory or
require learning the GraphQL syntax.
</p>
<p>
Additionally, our team wanted to include the option for developers
to be able to automatically deploy their configured Gateway on AWS
with minimal effort. Synapse provides a single command for deploying
to AWS once the Gateway has been configured.
</p>
<p>
Lastly, our team aimed to allow the developer an easy way to monitor
all requests coming through their new Gateway. Synapse creates a
monitoring dashboard for viewing request latencies, as well as any
errors produced by requests that hit the Gateway. We will explain
these features thoroughly later in our case study.
</p>
</div>
</div>
<!-- Section 5 -->
<div class="case-study-section">
<div class="case-study-subsection">
<h2>5. Who Should Use Synapse?</h2>
</div>
<div class="case-study-subsection">
<h3>5.1 Existing Solutions</h3>
<figure>
<img
src="assets/images/case-study/table-no-synapse.png"
class="case-study-image enlarge"
/>
<figcaption>
Fig. 14: Existing GraphQL API Gateway Solutions
</figcaption>
</figure>
<p>
When it comes to solutions for creating a GraphQL API gateway,
companies have a few options as seen in Figure 14. It is important
to note there aren’t really any managed solutions that use
Federation due the logic having to be interspersed within underlying
services. A small company may be able to utilize federation
themselves in a DIY fashion, but they may not have the resources or
time needed for training developers to learn the federation
specification and then reworking all their legacy APIs and data
sources. Let’s look at the options for a small company that does not
have a lot of time or resources to spend and would like to keep
their legacy APIs and data sources unaltered.
</p>
<p>
First, they could pick an integration platform as a service option
(IPaaS) such as AWS AppSync. Such a service will have a lot of
features, including an intuitive GUI interface for setting up the
gateway, as well as extensive monitoring and security features. The
downside would be that such a service could be very costly for a
small company and would limit the company’s flexibility to move
platforms in the future, inducing getting locked into a specific
vendor like AWS.
</p>
<p>
Additionally, they could choose an open-core option like GraphQL
Portal. Using this type of service, they would have the flexibility
of deploying where they want, the ease of easy configuration through
an intuitive GUI, as well as many additional features including
monitoring and security. The downside of this option would be that a
small company may not be able to afford the cost of using the full
features of this service on top of the deployment cost.
</p>
<p>
Third, they could opt to create the Gateway themselves manually.
This would allow the company the freedom to host where they want,
while also creating whatever features they deem necessary for their
unique situation. However, for a small company, the complexity of
creating all the features and doing it manually may drive the cost,
in terms of training their employees and development time, much too
high. Their employees may be new to GraphQL and they may not have
the resources and time to go through the training and development
process.
</p>
<p>
Synapse was created to fill a void for a small company that may not
have all their needs met by the existing solutions.
</p>
</div>
<div class="case-study-subsection">
<h3>5.2 Synapse vs. Existing Solutions</h3>
<figure>
<img
src="assets/images/case-study/table-synapse.png"
class="case-study-image enlarge" style="max-width: 850px"
/>
<figcaption>
Fig. 15: Solutions for a GraphQL API Gateway Solutions
</figcaption>
</figure>
<p>
As seen in figure 15, Synapse provides an easy and intuitive GUI for
configuration and monitoring, and gives the company the option to
deploy where they want. Synapse stands out by offering a feature to
automatically deploy onto AWS. The only cost involved with using
Synapse would be the cost of hosting on AWS. Everything else is free
and open source. Although Synapse looks attractive compared to other
options, it does have the tradeoff of not providing quite as many
features as other services. However, this is a tradeoff a small company
may be willing to make to keep costs low and get a GraphQL Gateway up and
connected to their existing infrastructure easily and quickly.
</p>
</div>
</div>
<!-- Section 6 -->
<div class="case-study-section">
<div class="case-study-subsection">
<h2>6. Synapse Walkthrough</h2>
<figure>
<img
src="assets/images/case-study/synapse-steps.png"
class="case-study-image"
/>
<figcaption>Fig. 16: Four Phases of Synapse</figcaption>
</figure>
<p>
As you can see in Figure 16, using Synapse is split into four
phases. First, the developer will download and set up Synapse on
their local machine. Then, they use the provided GUI interface, more
formally known as the Gateway Manager, to configure their Synapse
GraphQL Gateway. Once configured, the developer is able to test out
their Gateway on their local machine using the Apollo server
provided in the gateway. Lastly, if desired, the developer can
deploy Synapse onto AWS where the Synapse architecture will be
modified, preparing it for high volume traffic.
</p>
<p>
Since the architecture changes slightly in production, Synapse
technically has two states: one for configuration and one for
production. In configuration, everything is run on the developer’s
local machine. They download Synapse, and start it up on their local
machine. They then configure the GraphQL Gateway. Once configured,
the Gateway can be connected to live data sources to be tested on their local machine.
</p>
<p>
After testing of the Gateway, the developer is able to deploy
Synapse into production, where their Synapse application will now be
hosted and run on AWS. At this point, Synapse is in the production
state and the developer loses the ability to configure the Gateway
through the deployed Gateway Manager. However, this functionality is
replaced with management of users for the Gateway Manager.
Additionally, when deployed, Synapse will use a new MongoDB
database, removing all data from the configuration phase and being
seeded with the credentials of the root user. This allows the
production gateway data to be completely separate from testing data
that may have been collected during configuration.
</p>
<p>
Let’s investigate deeper, going through the four phases shown in
Figure 16.
</p>
</div>
<div class="case-study-subsection">
<h3>6.1 Download and Setup</h3>
<p>
To start, the developer must first download and configure Synapse to
run on their local machine. They are able to do so by running the
command
<code>npx @synapse-team/start-synapse</code>. This command will
prompt the user for a couple inputs, and then will set up Synapse on
their local machine so it can be started right away.
</p>
<p>
Afterwards, the developer is able to start using Synapse on their
local machine by running the command <code>synapse up</code>. This
will start up and run the entire architecture on the developer’s
local machine. Keep in mind, this architecture is Synapse in its
configuration state, as shown in Figure 17.
</p>
<figure>
<img
src="assets/images/case-study/local-architecture.png"
class="case-study-image shrink"
/>
<figcaption>
Fig. 17: Synapse Architecture in Configuration State
</figcaption>
</figure>
<p>
Synapse consists of three components: the GraphQL Gateway, the
Gateway Manager, and MongoDB. Each part is containerized via Docker
and when the <code>synapse up</code> command is run, a
docker-compose file is used to start up all three containers.
</p>
</div>
<div class="case-study-subsection">
<h3>6.2 Configure</h3>
<p>