/
summary.yaml
197 lines (189 loc) · 7.89 KB
/
summary.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
swagger: '2.0'
info:
version: '1.0.0-beta'
title: MediaWiki Summary API
description: Page content summary API
termsofservice: https://github.com/wikimedia/restbase#restbase
contact:
name: Services
email: services@lists.wikimedia.org
url: https://www.mediawiki.org/wiki/Services
license:
name: Apache licence, v2
url: https://www.apache.org/licenses/LICENSE-2.0
paths:
/summary/{title}:
x-route-filters:
- path: ./lib/revision_table_access_check_filter.js
options:
redirect_cache_control: '{{options.response_cache_control}}'
- path: ./lib/ensure_content_type.js
get:
tags:
- Page content
summary: Get a text extract & thumb summary of a page.
description: |
The summary response includes a text extract of the first several
sentences, as well as information about a thumbnail that represents
the page.
Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
produces:
- application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.1.2"
parameters:
- name: title
in: path
description: "Page title. Use underscores instead of spaces. Example: `Main_Page`."
type: string
required: true
- name: redirect
in: query
description: >
Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects)
return HTTP 302 with a redirect target in `Location` header and content in the body.
To get a 200 response instead, supply `false` to the `redirect` parameter.
type: boolean
required: false
responses:
'200':
description: The summary for the given page
schema:
$ref: '#/definitions/summary'
headers:
ETag:
description: >
Syntax: "{revision}/{tid}".
Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"
'301':
description: |
A permanent redirect is returned if the supplied article title was not in the normalized form.
To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
title normalization client-side.
Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
'302':
description: |
The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
The `location` header points to the redirect target.
If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.
Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
'404':
description: Unknown page title
schema:
$ref: '#/definitions/problem'
default:
description: Error
schema:
$ref: '#/definitions/problem'
x-setup-handler:
# Set up a simple key-value bucket.
- init:
method: 'put'
uri: /{domain}/sys/key_value/summary
body:
valueType: 'json'
x-request-handler:
- storage:
request:
method: get
headers:
cache-control: '{{cache-control}}'
uri: /{domain}/sys/key_value/summary/{request.params.title}
catch:
status: 404
return_if:
# Typical case: Return straight from storage.
status: '2xx'
return:
status: 200
headers:
content-type: '{{storage.headers.content-type}}'
etag: '{{storage.headers.etag}}'
cache-control: '{{options.response_cache_control}}'
body: '{{storage.body}}'
# Storage miss. Call the Action API to get the textextract.
- extract:
request:
method: post
uri: /{domain}/sys/action/query
body:
prop: 'info|extracts|pageimages|revisions|pageterms|coordinates'
exsentences: 5
explaintext: true
exintro: true
piprop: 'thumbnail|original'
inprop: 'displaytitle'
pithumbsize: 320
pilicense: 'any'
rvprop: 'timestamp|ids'
titles: '{{request.params.title}}'
wbptterms: 'description'
response:
# Define the response to save & return.
headers:
content-type: application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Summary/1.1.2"
etag: "\"{{getRevision(extract.body.items[0].revisions).revid}}/{{timeuuid()}}\""
body:
title: '{{extract.body.items[0].title}}'
displaytitle: '{{extract.body.items[0].displaytitle}}'
pageid: '{{extract.body.items[0].pageid}}'
extract: '{{extract.body.items[0].extract}}'
thumbnail: '{{httpsSource(extract.body.items[0].thumbnail)}}'
originalimage: '{{httpsSource(extract.body.items[0].original)}}'
lang: '{{extract.body.items[0].pagelanguagehtmlcode}}'
dir: '{{extract.body.items[0].pagelanguagedir}}'
timestamp: '{{getRevision(extract.body.items[0].revisions).timestamp}}'
description: '{{extractDescription(extract.body.items[0].terms)}}'
coordinates: '{{processCoords(extract.body.items[0].coordinates)}}'
- store_and_return:
request:
method: put
uri: /{domain}/sys/key_value/summary/{request.params.title}
headers: '{{merge({"if-none-hash-match": "*"}, extract.headers)}}'
body: '{{extract.body}}'
# With the if-none-hash-match header the storage will return 204 if the content is not changed,
# se we can return from the handler right away and avoid issuing purges.
return_if:
status: 204
return:
status: 200
headers:
content-type: '{{extract.headers.content-type}}'
etag: '{{store_and_return.headers.etag}}'
cache-control: '{{options.response_cache_control}}'
body: '{{extract.body}}'
- emit_change_event:
request:
method: post
uri: /{domain}/sys/events/
body:
- meta:
uri: //{request.params.domain}/api/rest_v1/page/summary/{request.params.title}
return:
status: 200
headers:
content-type: '{{extract.headers.content-type}}'
etag: '{{store_and_return.headers.etag}}'
cache-control: '{{options.response_cache_control}}'
body: '{{extract.body}}'
x-monitor: true
x-amples:
- title: Get summary from storage
request:
params:
domain: en.wikipedia.org
title: Barack_Obama
response:
status: 200
headers:
etag: /.+/
content-type: /^application\/json/
body:
extract: /.+/
thumbnail:
source: /^https:/
originalimage:
source: /^https:/
lang: en
dir: ltr
description: /.+/