-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathswagger.yaml
235 lines (231 loc) · 12.4 KB
/
swagger.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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
swagger: "2.0"
info:
version: "1"
title: "Pulse OpenAPI specification"
description: |
Pulse recommendation API based on [JSON Feed format](https://jsonfeed.org/version/1.1)
#### The Structure of a Feed:
* Feed starts with header at the top, there is a lot of information about feed in general, such as:
- where the feed comes from.
- feed icons.
- url to catch other feed items
- list of authors of this feed
- feed language
* After that there’s an array of objects — items — that describe each object in the list. Every item can have some fields like:
- main items data, like: *id*, *url*, *feed*, etc...
- optional attachments array with additional data for particular item
- tags array for particular feed item
- authors array for feed item
If you wish to get feed by category, it's enougth to specify the name of stream with needed documents.
#### Limitations:
* Feed readers are strongly advised to use [Conditional GET](https://fishbowl.pastiche.org/2002/10/21/http_conditional_get_for_rss_hackers/), in order to minimize bandwidth and CPU cycles on clients and servers.
contact:
email: "[email protected]"
x-apisguru-categories:
- news
- media
x-logo:
url: 'https://ps.w.org/mihdan-mailru-pulse-feed/assets/icon.svg?rev=2362563'
host: "api.pulse.mail.ru"
basePath: "/"
schemes:
- "https"
paths:
/v1/recomends:
get:
tags:
- "Recomendations"
summary: "Get recomendations from recostream service"
description: |
Allows to get items with recommended feed elements. State of the feed saved on a backend.
If feed is finished, you will get empty items list '\"items\":[]'
parameters:
- in: query
name: stream_id
schema:
type: string
description: Name of the feed you are trying to get
required: true
example: mail_ru_main
- in: query
name: n
default: 12
schema:
type: integer
description: Number of items
example: 5
operationId: "recomends"
produces:
- "application/json"
responses:
200:
description: "Ok"
schema:
$ref: "#/definitions/response_ok"
definitions:
response_ok:
type: object
properties:
version:
type: string
required: true
description: URL of the version of the format the feed uses. This should appear at the very top, though we recognize that not all JSON generators allow for ordering.
example: https://jsonfeed.org/version/1.1
title:
type: string
required: true
description: Name of the feed, which will often correspond to the name of the website (blog, for instance), though not necessarily.
example: why swagger?
home_page_url:
type: string
description: URL of the resource that the feed describes. This resource may or may not actually be a “home” page, but it should be an HTML page. If a feed is published on the public web, this should be considered as required. But it may not make sense in the case of a file created on a desktop computer, when that file is not shared or is shared only privately.
example: https://example.org
feed_url:
type: string
description: URL of the feed, and serves as the unique identifier for the feed. As with *home_page_url*, this should be considered required for feeds on the public web.
description:
type: string
description: provides more detail, beyond the 'title', on what the feed is about. A feed reader may display this text.
user_comment:
type: string
description: description of the purpose of the feed. This is for the use of people looking at the raw JSON, and should be ignored by feed readers.
next_url:
type: string
description: URL of a feed that provides the next n items, where n is determined by the publisher. This allows for pagination, but with the expectation that reader software is not required to use it and probably won’t use it very often. *next_url* must not be the same as *feed_url*, and it must not be the same as a previous *next_url* (to avoid infinite loops).
icon:
type: string
description: URL of an image for the feed suitable to be used in a timeline, much the way an avatar might be used. It should be square and relatively large — such as 512 x 512 pixels — so that it can be scaled-down and so that it can look good on retina displays. It should use transparency where appropriate, since it may be rendered on a non-white background.
favicon:
type: string
description: URL of an image for the feed suitable to be used in a source list. It should be square and relatively small, but not smaller than 64 x 64 pixels (so that it can look good on retina displays). As with icon, this image should use transparency where appropriate, since it may be rendered on a non-white background.
authors:
type: array
description: specifies one or more feed authors. The author object has several members. These are all optional — but if you provide an author object, then at least one is required.
items:
type: object
properties:
name:
type: string
example: Alexander Pushkin
url:
type: string
example: https://some.url.next
avatar:
type: string
example: https://avatar/data.png
language:
type: string
example: en-US
description: is the primary language for the feed in the format specified in [RFC 5646](https://tools.ietf.org/html/rfc5646). The value is usually a 2-letter language tag from [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), optionally followed by a region tag.
expired:
type: boolean
description: says whether or not the feed is finished — that is, whether or not it will ever update again. A feed for a temporary event, such as an instance of the Olympics, could expire. If the value is *true*, then it’s expired. Any other value, or the absence of expired, means the feed may continue to update.
hubs:
type: array
description: describes endpoints that can be used to subscribe to real-time notifications from the publisher of this feed.
items:
type: object
properties:
type:
type: string
required: true
url:
type: string
required: true
items:
type: array
items:
type: object
properties:
id:
type: string
example: ab123cda
description: unique for that item for that feed over time. If an item is ever updated, the *id* should be unchanged. New items should never use a previously-used *id*. Ideally, the *id* is the full URL of the resource described by the item, since URLs make great unique identifiers.
required: true
url:
type: string
description: URL of the resource described by the item. It’s the permalink. This may be the same as the *id* — but should be present regardless.
example: "https://example.com/resource"
external_url:
type: string
example: "https://example.com"
description: URL of a page elsewhere. This is especially useful for linkblogs. If *url* links to where you’re talking about a thing, then *external_url* links to the thing you’re talking about.
title:
type: string
example: my awesome title
description: microblog items in particular may omit titles.
summary:
type: string
example: best summary ever
description: is a plain text sentence or two describing the item. This might be presented in a timeline, for instance, where a detail view would display all of content_html or content_text.
content_html:
type: string
description: the only place HTML is allowed in this format is in. *content_html* or *content_text* one or both must be present
example: "<html<body><p>This is a paragraph.</p></body></html>"
content_text:
type: string
description: text of content. *content_html* or *content_text* one or both must be present, HTML not allowed, use *content_html* instead
image:
type: string
example: "http://to.some.img/data.png"
description: the URL of the main image for the item. This image may also appear in the *content_html* — if so, it’s a hint to the feed reader that this is the main, featured image. Feed readers may use the image as a preview (probably resized as a thumbnail and placed in a timeline).
banner_image:
type: string
example: "http://to.some.img/data.png"
description: the URL of an image to use as a banner. Some blogging systems (such as [Medium](https://medium.com/)) display a different banner image chosen to go with each post, but that image wouldn’t otherwise appear in the content_html. A feed reader with a detail view may choose to show this banner image at the top of the detail view, possibly with the title overlaid.
date_published:
type: string
example: "2010-02-07T14:04:00-05:00"
description: specifies the date in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
date_modified:
type: string
example: "2000-01-11T14:04:00-05:31"
description: specifies the modification date in [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
authors:
type: array
description: has the same structure as the top-level *authors*. If not specified in an item, then the top-level *authors*, if present, are the authors of the item.
items:
type: object
properties:
name:
type: string
example: Peter Griffin
url:
type: string
example: "https://example.com"
avatar:
type: string
example: "avatar/face.png"
language:
type: string
example: ru-RU
description: the language for this item, using the same format as the top-level *language* field. The value can be different than the primary language for the feed when a specific item is written in a different language than other items in the feed.
tags:
type: array
description: can have any plain text values you want. Tags tend to be just one word, but they may be anything. They are not the equivalent of Twitter hashtags. Some blogging systems and other feed formats call these categories.
items:
type: string
example: "animals"
attachments:
type: array
description: An individual item may have one or more attachments.
items:
type: object
properties:
url:
type: string
required: true
description: specifies the location of the attachment.
mime_type:
type: string
required: true
description: specifies the type of the attachment, such as “audio/mpeg.”
title:
type: string
description: is a name for the attachment. Important- if there are multiple attachments, and two or more have the exact same *title* (when *title* is present), then they are considered as alternate representations of the same thing. In this way a podcaster, for instance, might provide an audio recording in different formats.
size_in_bytes:
type: number
description: specifies how large the file is.
duration_in_seconds:
type: number
description: specifies how long it takes to listen to or watch, when played at normal speed.