Skip to content

Commit 40057b7

Browse files
AustinMusikuAustinMusiku
committed
Docs: Update READE.md
1 parent 454a602 commit 40057b7

File tree

1 file changed

+130
-81
lines changed

1 file changed

+130
-81
lines changed

‎README.md

Lines changed: 130 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,69 @@
11
# graphql-fpl-api
22

3-
GraphQL layer on top of the official fantasy premier league api.
4-
This is a the first of a two-part upgrade of my [fplfriend](https://fplfriend.up.railway.app/) app(You seriously need to check it out, it's awesome, I promise😉) where I focus on writing a decoupled backend using typescript and graphql as compared to the initial app version which was all written in javascript and used nodejs + ejs for templating. Although this api adds support for new data offered by the official fantasy premier league e.g., xG, xA, xGI, xGC, etc, it doesn't include all the data from the official api. I'll be adding more data as I need it for the frontend. If you need more data, feel free to open an issue and I'll add it.
3+
A Rich GraphQL proxy layer on top of the official Fantasy Premier League REST API
4+
5+
⚠️ This api does not support the two highly volatile data from the official api: gameweek live data and event status. This api relies heavily on caching to reduce the number of roundtrips to the official api and these two datasets are too dynamic to be cached without the risk of constantly serving stale data. An efficient cache invalidation strategy for this case is still being worked on.
6+
7+
[Try the live demo here](https://graphql-fpl-api.up.railway.app/graphql)
8+
9+
## Why graphql-fpl-api?
10+
11+
Consider the following query:
12+
13+
```graphql
14+
query Players {
15+
saka: player(id: 19) {
16+
...playerStats
17+
}
18+
salah: player(id: 308) {
19+
...playerStats
20+
}
21+
}
22+
23+
fragment playerStats on Player {
24+
first_name
25+
second_name
26+
total_points
27+
28+
upcoming_fixtures(first: 1) {
29+
is_home
30+
event
31+
difficulty
32+
team_h {
33+
name
34+
}
35+
team_a {
36+
name
37+
}
38+
}
39+
40+
past_fixtures {
41+
goals_scored
42+
assists
43+
opponent_team {
44+
name
45+
}
46+
}
47+
}
48+
```
49+
50+
In order to get the same data using the official REST api, you would have to make 4 separate requests:
51+
52+
```text
53+
1. https://fantasy.premierleague.com/api/bootstrap-static/ - 1.36 MB
54+
2. https://fantasy.premierleague.com/api/fixtures/ - 238.9 KB
55+
3. https://fantasy.premierleague.com/api/element-summary/19/ - 15.1 KB
56+
4. https://fantasy.premierleague.com/api/element-summary/308/ - 16.64 KB
57+
```
58+
59+
These 4 requests would, as of the time of writing this - 2023/24 season, return a total of `1.63 MB` of data transferred over the network. With graphql-fpl-api, you only need to make one request. This is a total of `763 B` (gzipped) transferred over the network. That's a `99.96%` reduction in data transferred over the network!
60+
61+
You might be worried that since graphql-fpl-api is a proxy layer on top of the official api, you would be making twice the number of roundtrips you would have made if you were to use the official api directly. This is not the case. As hinted earlier, graphql-fpl-api also caches the data from the official api. This means that you can make the same query multiple times and only the first request from the first client will hit the official api. Subsequent requests will be served from the cache. This is especially useful for data that doesn't change often like player data, game week data, and fixtures data.
562

663
## Getting started
764

865
### Installation
966

10-
#### prerequisites
11-
1267
1. Clone the repository to your local machine using `git clone https://github.com/AustinMusiku/graphql-fpl-api`
1368
2. Copy the contents of the `.env.example` file to a new file named `.env` and fill in the required fields.
1469

@@ -25,89 +80,85 @@ The api should now be test it out by visiting [http://localhost:4500/graphql](ht
2580

2681
## Usage
2782

28-
### Example query for a getting a player's data
83+
### Example query for a getting a manager's data
2984

3085
```graphql
31-
{
32-
saka: player(id: 13) {
33-
...arsenalPlayer
34-
}
35-
odegaard: player(id: 7) {
36-
...arsenalPlayer
37-
}
38-
salah: player(id: 283) {
39-
...liverpoolPlayer
40-
}
41-
alexander_Arnold: player(id: 285) {
42-
...liverpoolPlayer
43-
}
44-
}
45-
46-
fragment arsenalPlayer on Player {
47-
first_name
48-
second_name
49-
total_points
50-
}
51-
52-
fragment liverpoolPlayer on Player {
53-
web_name
54-
UpcomingFixtures(first: 2) {
55-
is_home
56-
difficulty
86+
query Manager {
87+
manager(id: 1528511) {
88+
player_first_name
89+
player_last_name
90+
leagues {
91+
classic {
92+
name
93+
entry_rank
94+
}
95+
}
96+
squad(gwId: 8) {
97+
picks {
98+
element {
99+
web_name
100+
}
101+
is_captain
102+
}
103+
}
57104
}
58105
}
59106
```
60107

61108
Produces the following response:
62109

63110
```json
64-
{
65-
"data": {
66-
"saka": {
67-
"first_name": "Bukayo",
68-
"second_name": "Saka",
69-
"total_points": 172
70-
},
71-
"odegaard": {
72-
"first_name": "Martin",
73-
"second_name": "Ødegaard",
74-
"total_points": 171
75-
},
76-
"salah": {
77-
"web_name": "Salah",
78-
"UpcomingFixtures": [
79-
{
80-
"is_home": true,
81-
"difficulty": 2
111+
"data": {
112+
"manager": {
113+
"player_first_name": "Austin",
114+
"player_last_name": "Musiku",
115+
"leagues": {
116+
"classic": [
117+
{
118+
"name": "Arsenal",
119+
"entry_rank": 575740
120+
},
121+
{
122+
"name": "Kenya",
123+
"entry_rank": 56656
124+
},
125+
{
126+
"name": "Gameweek 1",
127+
"entry_rank": 3334468
128+
},
129+
//...
130+
{
131+
"name": "DEVELOPERS PREMIER LEAGUE",
132+
"entry_rank": 4
133+
}
134+
]
135+
},
136+
"squad": {
137+
"picks": [
138+
{
139+
"element": {
140+
"web_name": "Areola"
82141
},
83-
{
84-
"is_home": false,
85-
"difficulty": 3
86-
}
87-
]
88-
},
89-
"alexander_Arnold": {
90-
"web_name": "Alexander-Arnold",
91-
"UpcomingFixtures": [
92-
{
93-
"is_home": true,
94-
"difficulty": 2
142+
"is_captain": false
143+
},
144+
// ...
145+
{
146+
"element": {
147+
"web_name": "Haaland"
95148
},
96-
{
97-
"is_home": false,
98-
"difficulty": 3
99-
}
100-
]
101-
}
102-
}
103-
}
149+
"is_captain": true
150+
}
151+
]
152+
}
153+
}
154+
}
104155
```
105156

106157
### Example query for a getting a specific gameweek's data
107158

108159
```graphql
109-
{
110-
gameweek(id: 15) {
160+
query Gameweek6 {
161+
gameweek(id: 6) {
111162
id
112163
deadline_time
113164
finished
@@ -127,36 +178,34 @@ Produces the following response:
127178
{
128179
"data": {
129180
"gameweek": {
130-
"id": 15,
131-
"deadline_time": "2022-11-05T13:30:00Z",
181+
"id": 6,
182+
"deadline_time": "2023-09-23T12:30:00Z",
132183
"finished": true,
133-
"highest_score": 123,
134-
"avg_points": 53,
184+
"highest_score": 142,
185+
"avg_points": 68,
135186
"chip_plays": [
136187
{
137188
"chip_name": "bboost",
138-
"num_played": 83164
189+
"num_played": 78528
139190
},
140191
{
141192
"chip_name": "freehit",
142-
"num_played": 61596
193+
"num_played": 60517
143194
},
144195
{
145196
"chip_name": "wildcard",
146-
"num_played": 150759
197+
"num_played": 283333
147198
},
148199
{
149200
"chip_name": "3xc",
150-
"num_played": 44333
201+
"num_played": 192955
151202
}
152203
]
153204
}
154205
}
155206
}
156207
```
157208

158-
For a full list of available queries and mutations, check out the schema explorer at [graphql-fpl-api.up.railway.app/graphql](https://graphql-fpl-api.up.railway.app/graphql)
159-
160209
## Contributing
161210

162211
I could use some help with writing tests. If you're interested in helping out, please feel free to open a pull request.

0 commit comments

Comments
 (0)