-
Notifications
You must be signed in to change notification settings - Fork 1
/
rapidoc.html
2288 lines (2286 loc) · 102 KB
/
rapidoc.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>
<!-- Important: must specify -->
<html>
<head>
<title>IGDB API</title>
<meta charset="utf-8" />
<!-- Important: rapi-doc uses utf8 characters -->
<script
type="module"
src="https://cdnjs.cloudflare.com/ajax/libs/rapidoc/9.3.4/rapidoc-min.min.js"
></script>
<link
rel="icon"
type="image/x-icon"
href="./assets/favicon.ico"
/>
<link
rel="stylesheet"
type="text/css"
href="./assets/rapidoc.css"
/>
</head>
<body>
<rapi-doc
spec-url="https://igdb-openapi.s-crypt.co/IGDB-OpenAPI.yaml"
heading-text="API UNOFFICIAL Docs"
fill-request-fields-with-example="true"
persist-auth="true"
theme="dark"
bg-color="#2e3336"
text-color="#f2f2f2"
header-color="#9147ff"
primary-color="#9147ff"
regular-font="Open Sans"
mono-font="Ubuntu Mono"
font-size="large"
show-method-in-nav-bar="as-colored-block"
use-path-in-nav-bar="true"
nav-bg-color="#1e2224"
nav-item-spacing="default"
render-style="read"
show-info="true"
show-components="true"
allow-spec-url-load="false"
allow-spec-file-load="false"
allow-spec-file-download="true"
show-curl-before-try="true"
schema-style="table"
schema-expand-level="1"
default-schema-tab="example"
server-url="https://corsproxy.io/?https://api.igdb.com/v4"
>
<img
slot="logo"
src="./assets/igdb_logo-svg.svg"
style="width: 75px; height: 75px; padding-inline: 20% 15%"
/>
<div slot="overview">
<br />
<h1 id="getting-started">Getting Started</h1>
<p>One of the principles behind IGDB.com is accessibility of data. We wish to share the data with anyone who wants to build cool video game oriented websites, apps and services.</p>
<p>This means that you are not only contributing to the value of IGDB but to thousands of other projects as well. We are looking forward to see what exciting game related projects you come up with. Happy coding!</p>
<p>For a high level overview of our juicy data, check out the <a href="#tag--Endpoints">endpoints section</a>.</p>
<br />
<aside style="text-align: center; color: white"><b>START USING US NOW, IT'S FREE!</b></aside>
<br />
<br />
<br />
<hr />
<br />
<h1
style="margin-left: -20px"
id="toc"
>
Table of Contents
</h1>
<ol>
<div class="header-link">
<li><a href="#account-creation">Account Creation</a></li>
<li><a href="#authentication">Authentication</a></li>
<li><a href="#requests">Requests</a></li>
<li><a href="#rate-limits">Rate Limits</a></li>
<li><a href="#wrappers">Wrappers</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#webhooks">Webhooks</a></li>
<li><a href="#reference">Reference</a></li>
<li><a href="#partnership">Partnership</a></li>
<li><a href="#faq">FAQ</a></li>
<li><a href="#support">Support</a></li>
<li><a href="#license">License</a></li>
<li><a href="#tag--Endpoints">Endpoints</a></li>
</div>
</ol>
<br />
<hr />
<br />
<h2
style="margin-left: -20px"
id="account-creation"
>
<a
href="#"
class="header-link"
>Account Creation</a
>
</h2>
<p>In order to use our API, you must have a Twitch Account.</p>
<ol>
<li>Sign Up with <a href="https://dev.twitch.tv/login">Twitch</a> for a free account</li>
<li>Ensure you have Two Factor Authentication <a href="https://www.twitch.tv/settings/security">enabled</a></li>
<li>Register your application in the <a href="https://dev.twitch.tv/console/apps/create">Twitch Developer Portal</a></li>
<li><a href="https://dev.twitch.tv/console/apps">Manage</a> your newly created application</li>
<li>Generate a Client Secret by pressing [New Secret]</li>
<li>Take note of the Client ID and Client Secret</li>
</ol>
<p>
The IGDB.com API is free for <strong>non-commercial</strong> usage under the terms of the
<a
rel="“nofollow”"
href="https://www.twitch.tv/p/legal/developer-agreement/"
>Twitch Developer Service Agreement</a
>.
</p>
<aside class="info"><b>Note:</b> We offer commercial partnership for users with a commercial need in their projects. For more details on that process please reach out to <a href="mailto: partner@igdb.com">partner@igdb.com</a></aside>
<br /><br />
<br />
<hr />
<br />
<h2
style="margin-left: -20px"
id="authentication"
>
<a
href="#authentication"
class="header-link"
>Authentication</a
>
</h2>
<p>
Now that you have a Client ID and Client Secret you will be authenticating as a Twitch Developer using Oauth2.<br />
Detailed information can be found in the <a href="https://dev.twitch.tv/docs/authentication">Twitch Developer Docs</a>.
</p>
<p>Make a <code>POST</code> request to <code>https://id.twitch.tv/oauth2/token</code> with the following query string parameters, substituting your Client ID and Client Secret accordingly.</p>
<p><code>client_id=Client ID</code></p>
<p><code>client_secret=Client Secret</code></p>
<p><code>grant_type=client_credentials</code></p>
<h3 id="example">Example</h3>
<p>If your Client ID is <code>abcdefg12345</code> and your Client Secret is <code>hijklmn67890</code>, the whole url should look like the following.</p>
<code
><span style="display: flex"
><span><span style="color: #f92672">POST</span>: <span style="color: #ae81ff">https://id.twitch.tv/oauth2/token?client_id=abcdefg12345&client_secret=hijklmn67890&grant_type=client_credentials</span> </span></span
></code
>
<p>The response from this will be a json object containing the access token and the number of second until the token expires.</p>
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><br><code data-lang="json"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"access_token"</span>: <span style="color:#e6db74">"access12345token"</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"expires_in"</span>: <span style="color:#ae81ff">5587808</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"token_type"</span>: <span style="color:#e6db74">"bearer"</span>
</span></span><span style="display:flex;"><span>}</span></span><br></code></pre>
<aside><b>Note:</b> The <i>expires_in</i> shows you the number of seconds before the <i>access_token</i> will expire and must be refreshed.</aside>
<br /><br />
<br />
<hr />
<br />
<h2
style="margin-left: -20px"
id="requests"
>
<a
href="#requests"
class="header-link"
>Requests</a
>
</h2>
<ul>
<li>Most of the requests to the API will use the <code>POST</code> method</li>
<li>
The base URL is: <strong><a href="https://api.igdb.com/v4">https://api.igdb.com/v4</a></strong>
</li>
<li>
You define which endpoint you wish to query by appending <code>/{endpoint name}</code> to the base URL eg. <strong><a href="https://api.igdb.com/v4/games">https://api.igdb.com/v4/games</a></strong>
</li>
<li>
Include your <code>Client ID</code> and <code>Access Token</code> in the <code>HEADER</code> of your request so that your headers look like the following.
<ul>
<li>Take special care of the capitalisation. <code>Bearer</code> should be hard-coded infront of your <code>access_token</code></li>
</ul>
</li>
</ul>
<div>
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><br><code data-lang="yaml"><span style="display:flex; padding-left: 20px;"><span><span style="color:#f92672">Client-ID</span>: <span style="color:#ae81ff">Client ID</span>
</span></span><span style="display:flex; padding-left: 20px;"><span><span style="color:#f92672">Authorization</span>: <span style="color:#ae81ff">Bearer access_token</span></span></span><br></code></pre>
</div>
<ul>
<li>You use the <code>BODY</code> of your request to specify the fields you want to retrieve as well as any other filters, sorting etc</li>
</ul>
<strong>Note:</strong> If you are trying to make these requests via the Browser you will run into CORS errors as the API does not allow requests directly from browsers. You can use the built-in CORS proxy by selecting the <code>https://corsproxy.io/?https://api.igdb.com/v4</code> server above. USE AT YOUR OWN RISK as it is a third party proxy run by the people at corsproxy.io. <br />
<br />
<br />
<br />
<hr />
<br />
<h2
style="margin-left: -20px"
id="rate-limits"
>
<a
href="#rate-limits"
class="header-link"
>Rate Limits</a
>
</h2>
<p>There is a rate limit of <strong>4 requests per second</strong>. If you go over this limit you will receive a response with status code <code>429 Too Many Requests</code>.</p>
<p>You are able to have up to 8 <em>open</em> requests at any moment in time. This can occur if requests take longer than 1 second to respond when multiple requests are being made.</p>
<br />
<hr />
<br />
<h2
style="margin-left: -20px"
id="wrappers"
>
<a
href="#wrappers"
class="header-link"
>Wrappers</a
>
</h2>
<p>Get setup quickly by using one of these wrappers!</p>
<h3 id="apicalypse">Apicalypse</h3>
<ul>
<li><a href="https://github.com/igdb/node-apicalypse">NodeJS</a></li>
<li><a href="https://github.com/husnjak/IGDB-API-JVM">JVM/Kotlin/Java</a></li>
<li><a href="https://github.com/husnjak/IGDB-SWIFT-API">Swift</a></li>
<li><a href="https://github.com/twitchtv/igdb-api-python">Python</a></li>
</ul>
<h3 id="third-party">Third Party</h3>
<ul>
<li><a href="https://github.com/marcreichel/igdb-laravel">PHP/Laravel</a></li>
<li><a href="https://github.com/Henry-Sarabia/apicalypse">GO</a></li>
<li><a href="https://github.com/ad2games/ruby-apicalypse">Ruby</a></li>
<li><a href="https://github.com/kamranayub/igdb-dotnet">C#/.NET</a></li>
</ul>
<br />
<hr />
<br />
<h1 id="examples">
<a
href="#examples"
class="header-link"
>Examples</a
>
</h1>
<p>It’s recommended to try out your queries in an API viewer like <a href="https://www.postman.com/">Postman</a> or <a href="https://insomnia.rest/">Insomnia</a> before using code. This helps you find problems a lot sooner!</p>
<p>Postman setup example</p>
<p>
<img
src="assets/postman1.png"
alt=""
/>
</p>
<p>
<img
src="assets/postman2.png"
alt=""
/>
</p>
<div style="margin-left: 30px">
<h3
style="margin-left: -20px"
id="a-very-basic-example-to-retrieve-the-name-for-10-games"
>
A very basic example to retrieve the name for 10 games.
</h3>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>fields name; limit 10;
</code></pre>
<h3
style="margin-left: -20px"
id="get-all-information-from-a-specific-game"
>
Get all information from a specific game
</h3>
<p>1942, is the ID of a game.</p>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>fields *; where id = 1942;
</code></pre>
<h3
style="margin-left: -20px"
id="exclude-irrelevant-data-from-your-query"
>
Exclude irrelevant data from your query
</h3>
<p>Remove alternative_name from your result query</p>
<p>
<a href="https://api.igdb.com/v4/platforms/">https://api.igdb.com/v4/platforms/</a>
</p>
<pre tabindex="0"><code>fields *;<br>exclude alternative_name;
</code></pre>
<h3
style="margin-left: -20px"
id="get-all-games-from-specific-genres"
>
Get all games from specific genres
</h3>
<p>Notice how you can comma separate multiple IDs (8, 9, and 11). You can do this with games, companies and anything else. Also note that when you have multiple IDs they have to be surrounded by a parenthesis. Single ids can be queried both with and without the parenthesis.</p>
<p>
<a href="https://api.igdb.com/v4/genres/">https://api.igdb.com/v4/genres/</a>
</p>
<pre tabindex="0"><code>fields *; where id = (8,9,11);
</code></pre>
<h3
style="margin-left: -20px"
id="count-total-games-that-have-a-rating-higher-than-75"
>
Count total games that have a rating higher than 75
</h3>
<p>
<a href="https://api.igdb.com/v4/games/count">https://api.igdb.com/v4/games/count</a>
</p>
<pre tabindex="0"><code>where rating > 75;
</code></pre>
<h3
style="margin-left: -20px"
id="order-by-rating"
>
Order by rating
</h3>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>fields name,rating; sort rating desc;
</code></pre>
<h3
style="margin-left: -20px"
id="coming-soon-games-for-playstation-4"
>
Coming soon games for Playstation 4
</h3>
<p>
<a href="https://api.igdb.com/v4/release_dates/">https://api.igdb.com/v4/release_dates/</a>
</p>
<pre tabindex="0"><code>fields *; where game.platforms = 48 & date > 1538129354; sort date asc;
</code></pre>
<p>1538129354: Is the timestamp in milliseconds of 28/09/2018 (This you need to generate yourself) 48 Is the platform id of Playstation 4.</p>
<h3
style="margin-left: -20px"
id="recently-released-games-for-playstation-4"
>
Recently released games for Playstation 4
</h3>
<pre tabindex="0"><code>fields *; where game.platforms = 48 & date < 1538129354; sort date desc;
</code></pre>
<aside class="info"><b>Note:</b> "where game.platforms = 48 & date > 1538129354" It is possible to use either & (AND) or | (OR) to combine filters to better define the behaviour of your query</aside>
<h3
style="margin-left: -20px"
id="search-return-certain-fields"
>
Search, return certain fields.
</h3>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>search "Halo"; fields name,release_date.human;
</code></pre>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>fields name, involved_companies; search "Halo";
</code></pre>
<h3
style="margin-left: -20px"
id="search-games-but-exclude-versions-editions"
>
Search games but exclude versions (editions)
</h3>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>fields name, involved_companies; search "Assassins Creed"; where version_parent = null;
</code></pre>
<p>This will return search results with ID and name of the game but exclude editions such as “Collectors Edition”.</p>
<h3
style="margin-left: -20px"
id="searching-all-endpoints"
>
Searching all endpoints
</h3>
<aside class="info"><b>Note:</b> Search is now also it's own endpoint. Search is usable on: Characters, Collections, Games, Platforms, and Themes</aside>
<p>The example below searches for “Sonic the Hedgehog” which will find the Character Sonic, the collection Soninc the Hedgehog. And of course also several games with names containing Sonic the Hedgehog.</p>
<p>
<a href="https://api.igdb.com/v4/search">https://api.igdb.com/v4/search</a>
</p>
<pre tabindex="0"><code>fields *; search "sonic the hedgehog"; limit 50;
</code></pre>
<h3
style="margin-left: -20px"
id="get-versions-editions-of-a-game"
>
Get versions (editions) of a game
</h3>
<p>
<a href="https://api.igdb.com/v4/game_versions/">https://api.igdb.com/v4/game_versions/</a>
</p>
<pre tabindex="0"><code>fields game.name,games.name; where game = 28540;
</code></pre>
<p>The resulting object will contain all games that are a version of the game with id 28540</p>
<h3
style="margin-left: -20px"
id="get-the-parent-game-for-a-version"
>
Get the parent game for a version
</h3>
<p>
<a href="https://api.igdb.com/v4/games/">https://api.igdb.com/v4/games/</a>
</p>
<pre tabindex="0"><code>fields version_parent.*; where id = 39047;
</code></pre>
<p>The resulting object will contain all main games</p>
<h3
style="margin-left: -20px"
id="get-all-games-that-are-playstation-4-exclusives"
>
Get all games that are playstation 4 exclusives
</h3>
<pre tabindex="0"><code>fields name,category,platforms;<br>where category = 0 & platforms = 48;
</code></pre>
<h3
style="margin-left: -20px"
id="get-all-games-that-are-only-released-on-playstation-4-and-pc"
>
Get all games that are only released on playstation 4 AND PC
</h3>
<pre tabindex="0"><code>fields name,category,platforms;<br>where category = 0 & platforms = {48,6};
</code></pre>
</div>
<br />
<hr />
<br />
<h1 id="webhooks">
<a
href="#webhooks"
class="header-link"
>Webhooks</a
>
</h1>
<div style="margin-left: 30px">
<h3
style="margin-left: -20px"
id="what"
>
What?
</h3>
<p>Webhooks allow us to push data to you when it is added, updated, or deleted. Instead of polling the API for changes, you can listen on your own HTTP endpoint (Webhook) and we will deliver the data to you.</p>
<p>Using Webhooks will ensure that your data is always up to date!</p>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="shell"><span style="display:flex;"><span>curl -X POST <span style="color:#e6db74">'https://api.igdb.com/v4/ENDPOINT/webhooks/'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-d <span style="color:#e6db74">'url=YOUR_WEBHOOK_URL&secret=YOUR_WEBHOOK_SECRET&method=create'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Client-ID: Client ID'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Authorization: Bearer access_token'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Content-Type: application/x-www-form-urlencoded'</span>
</span></span></code></pre>
</div>
<h3
style="margin-left: -20px"
id="how-to-register-your-webhook"
>
How to register your webhook
</h3>
<p>To register a new webhook you need to send a <code>POST</code> request to <code>ENDPOINT/webhooks</code>. The endpoint is required as it specifies what type of data you want from your webhook.</p>
<p>The post request should contain <code>x-www-form-urlencoded</code> body with three parameters:</p>
<ul>
<li><code>url</code> this is your prepared url that is ready to accept data from us.</li>
<li>
<code>method</code> this is the type of data you are expecting to your url, there are three types of methods
<ul>
<li><code>create</code>, sends new items from the API</li>
<li><code>delete</code>, sends deleted items from the API</li>
<li><code>update</code>, sends updated items from the API</li>
</ul>
</li>
<li><code>secret</code> this is your “secret” password for your webhook. Every request from the webhook service will have your secret in the header called <code>X-Secret</code>.</li>
</ul>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="yaml"><span style="display:flex;"><span><span style="color:#ae81ff">// Example response upon registering your webhook</span>
</span></span><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"id": </span><span style="color:#ae81ff">WEBHOOK_ID, // A unique ID for the webhook</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"url": </span><span style="color:#e6db74">"YOUR_WEBHOOK_URL"</span>, <span style="color:#ae81ff">// Your chosen URL</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"category": </span><span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">// Based on the endpoint you chose</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"sub_category": </span><span style="color:#ae81ff">0</span>, <span style="color:#ae81ff">// Based on your method (can be 0, 1, 2)</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"active": </span><span style="color:#66d9ef">true</span>, <span style="color:#ae81ff">// Is the webhook currently active</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"api_key": </span><span style="color:#e6db74">"YOUR_CLIENT_ID"</span>, <span style="color:#ae81ff">// Displays the api key the webhook is connected to</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"secret": </span><span style="color:#e6db74">"YOUR_SECRET"</span>, <span style="color:#ae81ff">// Your chosen secret</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"created_at": </span><span style="color:#e6db74">"2018-11-25T23:00:00.000Z"</span>, <span style="color:#ae81ff">// Created at date</span>
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"updated_at": </span><span style="color:#e6db74">"2018-11-25T23:00:00.000Z"</span> <span style="color:#ae81ff">// Updated at date</span>
</span></span><span style="display:flex;"><span>}
</span></span></code></pre>
</div>
<p>
<img
src="images/webhook_registration_postman.png"
alt=""
/><br />
Registering your webhook in Postman Once your webhook is registered you will receive a response with the new webhook object
</p>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="yaml"><span style="display:flex;"><span><span style="color:#ae81ff">// Delete Response from Webhook</span>
</span></span><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"id": </span><span style="color:#e6db74">"1234"</span>
</span></span><span style="display:flex;"><span>}
</span></span></code></pre>
</div>
<p>
That’s it!<br />
The data will now be sent to your webhook in the body of a post request. The data is a single json object representing an <strong>unexpanded entity</strong>.<br />
Webhooks from <strong>DELETE</strong> do not send the entire object but only the <strong>ID</strong>.
</p>
<aside class="info"><b>Tip!</b> Always validate your received data with you secret!</aside>
<p>Webhooks have an <code>active</code> field, as you can see in the JSON response above, The service will keep the webhook active as long as the webhook url is capable of receiving data from the service. If the url fails <strong>5</strong> times the webhook will be set to inactive (<code>active: false</code>) and the service will stop to send data to this webhook.</p>
<p>Reactivating the webhook is done by re-registering it, this will update the <code>active</code> status to true.</p>
<aside class="info"><b>Tip!</b> Re-register your webhook on service start, to make sure it's always active!</aside>
<h3
style="margin-left: -20px"
id="viewing-your-webhooks"
>
Viewing your webhooks
</h3>
<p>You can always get information about your webhooks from the API. To get ALL of your registered webhooks simply send a <code>GET</code> request to <code>/webhooks</code>, without the endpoint. This will return a JSON array of your webhooks</p>
<p>To get information about a specific webhook you can make a <code>GET</code> request with the webhook id to <code>/webhooks/WEBHOOK_ID</code>, without the endpoint. This will return the webhook of that id.</p>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="shell"><span style="display:flex;"><span><span style="color:#75715e"># Get ALL registered Webhooks</span>
</span></span><span style="display:flex;"><span>curl <span style="color:#e6db74">'https://api.igdb.com/v4/webhooks/'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Client-ID: Client ID'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Authorization: Bearer access_token'</span>
</span></span></code></pre>
</div>
<h3
style="margin-left: -20px"
id="viewing-your-webhooks-1"
>
Viewing your webhooks
</h3>
<p>You can always get information about your webhooks from the API. To get ALL of your registered webhooks simply send a <code>GET</code> request to <code>/webhooks</code>, without the endpoint. This will return a JSON array of your webhooks</p>
<p>To get information about a specific webhook you can make a <code>GET</code> request with the webhook id to <code>/webhooks/WEBHOOK_ID</code>, without the endpoint. This will return the webhook of that id.</p>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="shell"><span style="display:flex;"><span>curl -X DELETE <span style="color:#e6db74">'https://api.igdb.com/v4/webhooks/WEBHOOK_ID'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Client-ID: Client ID'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Authorization: Bearer access_token'</span>
</span></span></code></pre>
</div>
<h3
style="margin-left: -20px"
id="removing-a-webhook"
>
Removing a Webhook
</h3>
<p>To remove your existing webhook you need to send a <code>DELETE</code> request to <code>/webhooks/WEBHOOK_ID</code>, without the endpoint. The Webhook id is returned during the registration process or can be found with a <code>GET</code> request to <code>/webhooks/</code>.</p>
<p>The <code>DELETE</code> request will receive the deleted webhook as confirmation.</p>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="shell"><span style="display:flex;"><span>curl -X POST <span style="color:#e6db74">'https://api.igdb.com/v4/ENDPOINT/webhooks/test/WEBHOOK_ID?entityId=ENTITY_ID'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Client-ID: Client ID'</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>-H <span style="color:#e6db74">'Authorization: Bearer access_token'</span>
</span></span></code></pre>
<h3
style="margin-left: -20px"
id="testing"
>
Testing
</h3>
<p>To make sure you have everything setup just right we have a test endpoint for the webhook service. This endpoint will send an object of your choosing to your newly created webhook.</p>
<p>Send a <code>POST</code> request to <code>ENDPOINT/webhooks/test/WEBHOOK_ID?entityId=ENTITY_ID</code>. The entity id is the id of the object from the endpoint you wish to test with, example:</p>
<p>
<code>POST</code> to <code>games/webhooks/test/42?entityId=1337</code>:<br />
This request will send the game object with id 1337 to your webhook url.
</p>
<h3
style="margin-left: -20px"
id="handling-webhooks-on-your-end"
>
Handling Webhooks on your end
</h3>
<p>When recieveing the webhook message on your end what we expect is to recieve a <code>200 OK</code> back within <strong>15 seconds</strong>. If the endpoint takes longer than 15 seconds to respond the event will be deemed as a failed event, fail 5 times and the webhook will be set to inactive.</p>
</div>
<br />
<hr />
<br />
<h1 id="cors-proxy">
<a
href="#cors-proxy"
class="header-link"
>CORS Proxy</a
>
</h1>
<div style="margin-left: 30px">
<h2
style="margin-left: -20px"
id="cors"
>
CORS
</h2>
<p>If you intend to use our API from your website you will encounter an issue with security; namely CORS <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS">Cross-Origin Resource Sharing</a>.</p>
<p>There are security mechanisms in place by all major browsers to stop websites from accessing other domains without getting explicit permission. This is done through HTTP headers. So, for example, amazinggameswebsite.com cannot access api.igdb.com without us explicitly stating in the HTTP headers (Access-Control-Allow-Origin) that they have permission.</p>
<p>We do not offer the configuration of these headers as a service, so any browser-based javascript and mobile javascript frameworks will not be able to communicate directly with the IGDB API.</p>
<h3
style="margin-left: -20px"
id="workaround"
>
Workaround
</h3>
<p>See the guide for <a href="#proxy">setting up a proxy</a> or set up a proxy using <a href="https://github.com/Rob--W/cors-anywhere">CORS Anywhere</a></p>
<h2
style="margin-left: -20px"
id="proxy"
>
Proxy
</h2>
<p>There are a number of reasons why you may wish to proxy requests to the IGDB API.</p>
<ul>
<li>To have a backend that keeps track of your Oauth Application Tokens</li>
<li>Caching requests to the API for better performance</li>
<li>Enable application logging to track/debug usage</li>
<li>Enable CORS between the proxy and applications</li>
</ul>
<h3
style="margin-left: -20px"
id="how-do-i-set-up-a-proxy"
>
How do I set up a proxy?
</h3>
<p>Proxies can be complex, but to get you started we have a simple guide to get you up and running quickly through AWS.</p>
<p>We have provided a single link that will let you deploy an AWS Api Gateway in your own AWS account that will serve as a proxy. This Stack will also handle your Access Token rotations automatically for you, so you don’t need to think about that.</p>
<p>
<img
src="/assets/igdb_simple_proxy_transparent.png"
alt="Simple Api Proxy Diagram"
/>
</p>
<h3
style="margin-left: -20px"
id="what-will-it-cost"
>
What will it cost?
</h3>
<p>
AWS has a <a href="https://aws.amazon.com/api-gateway/pricing/">very generous free-tier</a> for new users and the services used in the provided solution (<a href="https://aws.amazon.com/api-gateway/pricing/">Api Gateway</a>, <a href="https://aws.amazon.com/secretsmanager/pricing/">Secrets Manager</a>, <a href="https://aws.amazon.com/lambda/pricing/">Lambda</a>). Please use the <a href="https://calculator.aws/#/estimate">AWS Pricing Calculator</a> to gauge how much this will cost you before
setting up your Stack.
</p>
<h3
style="margin-left: -20px"
id="stack-setup"
>
Stack Setup
</h3>
<p><strong>Prerequisites:</strong> You need to have an AWS account with permissions to deploy CloudFormation stacks.</p>
<ol>
<li>
Click this
<a
href="https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/create/review?stackName=simple-igdb-proxy&templateURL=https://api-simple-proxy-bucket.s3.amazonaws.com/api-simple-proxy.yml"
target="_blank"
>link</a
>
to get started.
</li>
<li>
Go over the Stack Details
<ul>
<li>You have to agree to the terms and conditions.</li>
<li>You have to fill in your <a href="https://dev.twitch.tv/">Twitch Application Credentials</a></li>
<li>It’s recommended to protect your proxy by enabling Api Keys</li>
<li><strong>NOTE:</strong> Enabling Caching will come with extra costs as this is NOT covered by the Free-tier</li>
<li><strong>NOTE:</strong> Enabling CORS will ‘break’ Protobuf responses, some libraries might not work.</li>
</ul>
</li>
<li>Click Next</li>
<li>Configure Stack Options - Nothing is required here, you can click Next</li>
<li>Verify Settings, click the checkbox at the bottom, then click “Create Stack”</li>
<li>You will now see the “Stack Details” screen, hit the refresh arrow button on the right until your stack name on the left says “UPDATE_COMPLETE”</li>
<li>
Click on the “Outputs” tab to get the URL to your new proxy.
<ul>
<li>The “Resources” tab summarises all the services deployed on your account.</li>
<li>The “Template” tab displays the template used for deployment.</li>
</ul>
</li>
<li>
You can now post requests to your URL and it will proxy to our API
<ul>
<li>If you enabled Api Keys you will need to specify the header <code>x-api-key</code> and the key can be found via a link through the “Resources” tab for “ApiDefaultKey”</li>
</ul>
</li>
</ol>
<p>
<strong>Important Note:</strong> The url generated will end in <code>production</code>, so you will want to post to<br />
<code>https://<your-api-gateway-unique-id>.execute-api.us-west-2.amazonaws.com/production/v4/games</code>
</p>
<p>
<img
src="/assets/simple-proxy-example-request.png"
alt="Example Request to Api Proxy"
/>
</p>
<h3
style="margin-left: -20px"
id="whats-next"
>
What’s next?
</h3>
<p>You can do a lot of things via <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started.html">API Gateway</a>.</p>
<ul>
<li>You can improve the security of your proxy by creating another sort of <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html">Authentication</a>, to prevent others from using up your RPS quota.</li>
<li>You can also setup your own Domain name and SSL with <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html">Route53</a></li>
<li>
You can modify the path of the proxy to have it serve as the front-end to your own APIs
<ul>
<li>Perform a calculation? <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-with-lambda-integration.html">Lambda Integration</a></li>
<li>Just want to store some records? <a href="https://aws.amazon.com/blogs/compute/using-amazon-api-gateway-as-a-proxy-for-dynamodb/">DynamoDB Integration</a></li>
<li>Want users to be able to upload/download files? <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/integrating-api-with-aws-services-s3.html">S3 Integration</a></li>
</ul>
</li>
<li>Enable request <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/security-monitoring.html">logging</a></li>
</ul>
<h3
style="margin-left: -20px"
id="alternatives"
>
Alternatives
</h3>
<ul>
<li>CORS: Setup a proxy using <a href="https://github.com/Rob--W/cors-anywhere">CORS Anywhere</a></li>
</ul>
</div>
<br />
<hr />
<br />
<h1 id="reference">
<a
href="#reference"
class="header-link"
>Reference</a
>
</h1>
<div style="margin-left: 30px">
<h2
style="margin-left: -20px"
id="images"
>
Images
</h2>
<aside class="info"><b>Note:</b> Images that are removed or replaced from IGDB.com exist for <b>30 days</b> before they are removed. Keep that in mind when designing cache logic.</aside>
<h3
style="margin-left: -10px"
id="examples-1"
>
Examples
</h3>
<ul>
<li>
Address:
<ul>
<li><code>https://api.igdb.com/v4/games/</code></li>
</ul>
</li>
<li>
Body:
<ul>
<li>
<code
>fields screenshots.*;<br />
where id = 1942;
</code>
</li>
</ul>
</li>
</ul>
<p>Here we retrieve the image properties of the game with the id “1942”</p>
<div class="highlight">
<pre
tabindex="0"
style="color: #f8f8f2; background-color: #272822; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4"
><code data-lang="json"><span style="display:flex;"><span>[{
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"id"</span>: <span style="color:#ae81ff">1942</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"screenshots"</span>: [{
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"id"</span>: <span style="color:#ae81ff">9742</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"game"</span>: <span style="color:#ae81ff">1942</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"height"</span>: <span style="color:#ae81ff">1080</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"image_id"</span>: <span style="color:#e6db74">"mnljdjtrh44x4snmierh"</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"url"</span>: <span style="color:#e6db74">"//images.igdb.com/igdb/image/upload/t_thumb/mnljdjtrh44x4snmierh.jpg"</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"width"</span>: <span style="color:#ae81ff">1920</span>
</span></span><span style="display:flex;"><span> },
</span></span><span style="display:flex;"><span> {
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"id"</span>: <span style="color:#ae81ff">9743</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"game"</span>: <span style="color:#ae81ff">1942</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"height"</span>: <span style="color:#ae81ff">1080</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"image_id"</span>: <span style="color:#e6db74">"em1y2ugcwy2myuhvb9db"</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"url"</span>: <span style="color:#e6db74">"//images.igdb.com/igdb/image/upload/t_thumb/em1y2ugcwy2myuhvb9db.jpg"</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">"width"</span>: <span style="color:#ae81ff">1920</span>
</span></span><span style="display:flex;"><span> }
</span></span><span style="display:flex;"><span> ]
</span></span><span style="display:flex;"><span>}]
</span></span></code></pre>
</div>
<p><strong>Image url structure:</strong></p>
<p><code>https://images.igdb.com/igdb/image/upload/t_screenshot_med_2x/dfgkfivjrhcksyymh9vw.jpg</code></p>
<p><strong>Break down:</strong></p>
<p><code>https://images.igdb.com/igdb/image/upload/t_{size}/{hash}.jpg</code></p>
<p><code>size</code> is one of the interchangeable size types listed below. <code>hash</code> is the id of the image. The image sizes are all maximum size but by appending <code>_2x</code> to any size, you can get retina (DPR 2.0) sizes (<code>cover_small_2x</code>).</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Size</th>
<th>Extra</th>
</tr>
</thead>
<tbody>
<tr>
<td>cover_small</td>
<td>90 x 128</td>
<td>Fit</td>
</tr>
<tr>
<td>screenshot_med</td>
<td>569 x 320</td>
<td>Lfill, Center gravity</td>
</tr>
<tr>
<td>cover_big</td>
<td>264 x 374</td>
<td>Fit</td>
</tr>
<tr>
<td>logo_med</td>
<td>284 x 160</td>
<td>Fit</td>
</tr>
<tr>
<td>screenshot_big</td>
<td>889 x 500</td>
<td>Lfill, Center gravity</td>
</tr>
<tr>
<td>screenshot_huge</td>
<td>1280 x 720</td>
<td>Lfill, Center gravity</td>
</tr>
<tr>
<td>thumb</td>
<td>90 x 90</td>
<td>Thumb, Center gravity</td>
</tr>
<tr>
<td>micro</td>
<td>35 x 35</td>
<td>Thumb, Center gravity</td>
</tr>
<tr>
<td>720p</td>
<td>1280 x 720</td>
<td>Fit, Center gravity</td>
</tr>
<tr>
<td>1080p</td>
<td>1920 x 1080</td>
<td>Fit, Center gravity</td>
</tr>
</tbody>
</table>
<h2
style="margin-left: -20px"
id="fields"
>
Fields
</h2>
<h3
style="margin-left: -10px"
id="what-1"
>
What?
</h3>
<p>Fields are properties of an entity. For example, a Game field would be <code>genres</code> or <code>release_dates</code>. Some fields have properties of their own, for example, the <code>genres</code> field has the property <code>name</code>.</p>
<h3
style="margin-left: -10px"
id="where"
>
Where?
</h3>
<p>Fields can be used on any entity that has sub-properties such as Games, Companies, People etc.</p>
<h3
style="margin-left: -10px"
id="how"
>
How?
</h3>
<p>Fields are requested in a comma separated list. For example, to get some information for some Games, Genres, Themes or anything else, you could request it like this:</p>
<p><strong>Apicalypse</strong></p>
<p>
<code>where id = (4356,189,444);</code><br />
<code>fields name,release_dates,genres.name,rating</code>
</p>
<p><strong>Legacy Parameters</strong></p>
<p><code>/games/4356,189,444?fields=name,release_dates,genres.name,rating</code></p>
<p>Note in Apicalypse the <code>name</code> property of <code>genres</code> can be accessed directly with a dot (genres.name).</p>
<p>A full list of fields can be obtained by passing a <code>*</code> as a field. Alternatively you can use the <code>meta</code> postfix: <code>/games/meta</code> to get a list of all fields.</p>
<h3
style="margin-left: -10px"
id="shorthand"
>
Shorthand
</h3>
<p>Another way of writing fields is to use the shorthand <strong>f</strong> which achieves the same result.</p>
<p>
<code>f name,release_dates,genres.name,rating;</code><br />
<code>w id = (4356,189,444);</code>
</p>
<h2
style="margin-left: -20px"
id="exclude"
>
Exclude
</h2>
<h3
style="margin-left: -10px"
id="what-2"
>
What?
</h3>
<p>Exclude is a complement to the regular fields which allows you to request all fields with the exception of any numbers of fields specified with exclude.</p>
<h3
style="margin-left: -10px"
id="how-1"
>
How?
</h3>
<p>Fields to be excluded are specified as a comma separated list. For example, to get all fields excpect for screenshots, you could request it like this:</p>
<p><strong>Apicalypse</strong></p>
<p>
<code>fields *;</code><br />
<code>exclude screenshots;</code>
</p>
<h3
style="margin-left: -10px"
id="shorthand-1"
>
Shorthand
</h3>
<p>Another way of writing exclude is to use the shorthand <strong>x</strong> which achieves the same result.</p>
<p>
<code>f *;</code><br />
<code>x screenshots;</code>
</p>
<h2
style="margin-left: -20px"
id="expander"
>
Expander
</h2>
<h3
style="margin-left: -10px"
id="what-3"
>
What?
</h3>
<p>Some fields are actually ids pointing to another endpoint. The expander feature is a convenient way to go into these other endpoints and access more information from them in the same query, instead of having to do multiple queries.</p>
<h3
style="margin-left: -10px"
id="where-1"
>
Where?
</h3>
<p>Expands are specificed among the regular fields in the body of the query.</p>
<h3