-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopen-api.yaml
217 lines (217 loc) · 6.95 KB
/
open-api.yaml
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
# This OpenAPI/Swagger specification file describes the back-end microservice
# REST API that the React front-end app is expecting to connect to.
openapi: 3.0.3
info:
title: readcommend
description: |
Readcommend is a book recommendation web app for the true book aficionados and disavowed
human-size bookworms. It allows to search for book recommendations with best ratings, based
on different search criteria.
servers:
- url: http://localhost:5000/api/v1
description: Local server
paths:
/books:
get:
summary: Gets ranked and filtered list of books
description: |
Gets list of books, ordered by rank from best to worst rated, with optional filters. Multiple
filters can be specified: author(s), genre(s), min/max number of pages, min/max published date,
as well as maximum number of results.
operationId: GetBooks
parameters:
- name: authors
in: query
required: false
description: |
Comma-delimited list of numeric author IDs. If multiple IDs are specified, the results will
include the union of all given authors, intersected with criteria of other types, if any.
When omitted, results will not be filtered by author.
example: 123,456,789
schema:
type: string
pattern: ^([0-9]+,)*[0-9]+$
- name: genres
in: query
required: false
description: |
Comma-delimited list of numeric genre IDs. If multiple IDs are specified, the results will
include the union of all given genres, intersected with criteria of other types, if any.
When omitted, results will not be filtered by genre.
example: 123,456,789
schema:
type: string
pattern: ^([0-9]+,)*[0-9]+$
- name: min-pages
in: query
required: false
description: Inclusive minimum number of pages.
schema:
type: integer
minimum: 1
maximum: 10000
- name: max-pages
in: query
required: false
description: Inclusive maximum number of pages.
schema:
type: integer
minimum: 1
maximum: 10000
- name: min-year
in: query
required: false
description: |
Inclusive minimum publishing year.
schema:
type: integer
minimum: 1800
maximum: 2100
- name: max-year
in: query
required: false
description: |
Inclusive maximum publishing year.
schema:
type: integer
minimum: 1800
maximum: 2100
- name: limit
in: query
required: false
description: |
Inclusive maximum number of results to return (defaults to all results).
schema:
type: integer
minimum: 1
responses:
200:
description: Json list of books
application/json:
schema:
type: object
example:
- id: 1
title: Alanna Saves the Day
yearPublished: 1972
rating: 1.62
pages: 169
genre:
id: 8
title: Childrens
author:
id: 6
firstName: Bernard
lastName: Hopf
- id: 2
title: Adventures of Kaya
yearPublished: 1999
rating: 2.13
pages: 619
genre:
id: 1
title: Young Adult
author:
id: 40
firstName: Ward
lastName: Haigh
400:
description: |
Bad Request, most likely because of invalid query parameters
application/json:
schema:
type: object
example:
message: invalid query parameters
/authors:
get:
summary: Gets all authors
description: |
Gets list of all authors. As this list would typically be quite huge in a
real production dataset, an important improvement would be to dynamically
query authors by first few characters as user is typing.
operationId: GetAuthors
responses:
200:
description: Json list of authors
application/json:
schema:
type: object
example:
- id: 1
firstName: Abraham
lastName: Stackhouse
- id: 2
firstName: Amelia
lastName: Wangerin, Jr.
- id: 3
firstName: Anastasia
lastName: Inez
/genres:
get:
summary: Gets all genres
description: |
Gets list of all genres.
operationId: GetGenres
responses:
200:
description: Json list of genres
application/json:
schema:
type: object
example:
- id: 1
title: Young Adult
- id: 2
title: SciFi/Fantasy
- id: 3
title: Romance
/sizes:
get:
summary: Gets all book size ranges
description: Gets list of all book size ranges.
operationId: GetSizes
responses:
200:
description: |
Json list of size ranges. Note that IDs are returned only as a convenience
for UI, but are not used for querying books of given size (use minPages
and maxPages as filtering criteria instead).
application/json:
schema:
type: object
example:
- id: 1
title: Short story – up to 35 pages
maxPages: 34
- id: 2
title: Novelette – 35 to 85 pages
minPages: 35
maxPages: 84
- id: 6
title: Monument – 800 pages and up
minPages: 800
/eras:
get:
summary: Gets all eras
description: |
Gets list of all eras (ranges of publishing years). Minimum
and maximum years are both inclusive and either of them
may be omitted for an unbounded range in either direction.
operationId: GetEras
responses:
200:
description: |
Json list of eras. Note that IDs are returned only as a convenience
for UI, but are not used for querying books of given era (use minYear
and maxYear as filtering criteria instead).
application/json:
schema:
type: object
example:
- id: 1
title: Classic
maxYear: 1969
- id: 2
title: Modern
minYear: 1970