-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathAPI.txt
251 lines (197 loc) · 16.7 KB
/
API.txt
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
RefBank data servlet (/RefBank/rbk):
GET (response content depends on action parameter):
action=admin (also as /RefBank/rbk/admin): retrieve login form for the RefBank node administration HTML page (used in browser, not part of API)
action=nodes (also as /RefBank/rbk/nodes): retrieve list of other RefBank nodes known to this one
additional parameters: none
response (MIME type text/xml, encoding UTF-8):
<nodes>
<node name="name of RefBank node" accessUrl="preferred access URL of node" />
<node ... />
</nodes>
action=ping (also as /RefBank/rbk/ping): ping node
additional parameters: none
response (MIME type text/xml, encoding UTF-8):
<nodes />
action=name (also as /RefBank/rbk/name): retrieve data of this RefBank node
additional parameters: none
response (MIME type text/xml, encoding UTF-8):
<nodes>
<node name=&qout;<name of RefBank node>&qout; accessUrl="preferred access URL of node" />
</nodes>
action=feed: retrieve the reference update feed, ordered by increasing update time
additional parameters:
updatedSince: minimum update time for references to include in the feed, formatted as UTC HTTP timestamp
response: compact feed of references updated since the specified timestamp (MIME type text/xml, encoding UTF-8)
<refSet>
<ref id="reference ID" canonicalId="ID of canonical reference" deleted="deleted flag, true or false" createTime="UTC timestamp reference was first added to RefBank" updateTime="UTC timestamp reference was last updated" localUpdateTime="UTC timestamp reference was last updated on this RefBank node" parseChecksum="MD5 hash of parsed version, if available" />
<ref ... />
</refSet>
action=rss: retrieve an RSS feed announcing recently added references, ordered by decreasing upload time
additional parameters:
top: number of references to include in the feed (defaults to 100 if not specified)
response: an RSS feed announcing the latest additions (MIME type application/rss+xml, encoding UTF-8)
action=count: retrieve the number of references stored in the node
additional parameters:
since: the UTC timestamp since which to count the references (optional, defaults to 0)
format: the format to represent the response (optional, defaults to the native XML representation if omitted)
response: the number of references stored in the node (MIME type text/xml, encoding UTF-8)
<refSet count="number of strings" since="argument since" />
action=get: resolve RefBank internal identifiers
additional parameters:
id: the identifier(s) to resolve, can be multi-valued
format: the format to represent the parsed versions of references in (optional, defaults to the native MODS XML representation if omitted)
response: the reference(s) with the specified identifier(s) (MIME type text/xml, encoding UTF-8)
<refSet>
<ref id="reference ID" canonicalId="ID of canonical reference" deleted="deleted flag, true or false" createTime="UTC timestamp reference was first added to RefBank" createUser="name of the user to first add reference to RefBank" createDomain="name of RefBank node reference was first added to" updateTime="UTC timestamp reference was last updated" updateUser="name of the user to last update reference" updateDomain="name of RefBank node reference was last updated at">
<refString><plain reference string></refString>
<refParsed><parsed version of reference (if available), as MODS XML or in format specified by format parameter></refParsed>
</ref>
<ref>...</ref>
</refSet>
action=find: search references
additional parameters:
query: full text query against reference strings, can be multi-valued
combine: or or and, controls if multiple full text queries are combined conjunctively (the default) or disjunctively
type: type of reference, only finds references with parsed version available
user: contributing user
author: query against author attribute of references, only finds references with parsed version available
title: query against title attribute of references, only finds references with parsed version available
date: query against year of publication attribute of references, only finds references with parsed version available
origin: query against origin of references (journal + volume number, publisher or location, as well as volume title), only finds references with parsed version available
format=concise: exclude parsed version of references from response
format: the name of the format for representing the parsed version of the references (defaults to the native MODS XML if not specified)
limit: the maximum number of references to include in the search result (0, the default, means no limit)
sco: set to sco to restrict search results to references not marked as duplicates of others
response: the reference matching the specified search criteria (MIME type text/xml, encoding UTF-8)
<refSet>
<ref id="reference ID" canonicalId="ID of canonical reference" deleted="deleted flag, true or false" createTime="UTC timestamp reference was first added to RefBank" createUser="name of the user to first add reference to RefBank" createDomain="name of RefBank node reference was first added to" updateTime="UTC timestamp reference was last updated" updateUser="name of the user to last update reference" updateDomain="name of RefBank node reference was last updated at" parseChecksum="MD5 hash of parsed version, if available and format set to concise">
<refString><plain reference string></refString>
<refParsed><parsed version of reference (if available), as MODS XML or in format specified by format parameter></refParsed>
</ref>
<ref ...>...</ref>
</refSet>
action=apiStats: retrieve statistics on the usage of the node, in particular for the data handling actions
additional parameters:
format: the name of the XSLT stylesheet to use for transforming the result (defaults to the native XML if not specified)
response: the API call statistics (MIME type text/xml, encoding UTF-8)
<apiStats total="total number of API calls" feed="number of calls to feed action" rss="number of calls to RSS feed action" find="number of calls to find action" get="number of calls to get action" update="number of calls to update action" count="number of calls to count action" stats="number of calls to API statistics"/>
POST: requests from RefBank node administration HTML page, infrastructure replication, or meta data updates for existing references:
/RefBank/rbk/update: for deleting or un-deleting existing references or updating canonical reference ID
request headers to set:
user: the user to credit for the update
request body:
<refSet>
<ref id="reference ID" canonicalId="ID of canonical reference to set" deleted="deleted flag to set, true or false"/>
</refSet>
response (MIME type text/xml, encoding UTF-8):
<refSet>
<ref id="reference ID" canonicalId="ID of canonical reference" deleted="deleted flag, true or false" createTime="UTC timestamp reference was first added to RefBank" createUser="name of the user to first add reference to RefBank" createDomain="name of RefBank node reference was first added to" updateTime="UTC timestamp reference was last updated" updateUser="name of the user to last update reference" updateDomain="name of RefBank node reference was last updated at" parseChecksum="MD5 hash of parsed version, if available">
<refString><plain reference string></refString>
</ref>
</refSet>
/RefBank/rbk/admin: process input from the RefBank node administration HTML page (used in browser, not part of API)
/RefBank/rbk/nodes: retrieve list of other RefBank nodes known to this one
request body: none
response (MIME type text/xml, encoding UTF-8):
<nodes>
<node name="name of RefBank node" accessUrl="preferred access URL of node" />
<node ... />
</nodes>
/RefBank/rbk/ping: ping node
request body: none
response (MIME type text/xml, encoding UTF-8):
<nodes />
/RefBank/rbk/name: retrieve data of this RefBank node
request body: none
response (MIME type text/xml, encoding UTF-8):
<nodes>
<node name="name of RefBank node" accessUrl="preferred access URL of node" />
</nodes>
/RefBank/rbk/introduce: introduce a new RefBank node to this one, retrieve list of other known RefBank nodes
request body (parameters):
name: the name of the RefBank node introducing itself
accessUrl: the preferred access URL of the RefBank node introducing itself
response (MIME type text/xml, encoding UTF-8):
<nodes>
<node name="name of RefBank node" accessUrl="preferred access URL of node" />
<node ... />
</nodes>
PUT: upload new or update existing references:
request headers to set:
Data-Format: the upload data format, xml or txt (tried to auto-detect if not specified)
User-Name: the user to credit for uploaded references (defaults to 'Anonymous' if not specified)
request body: the references as plain text or wrapped in XML, corresponding to the format specified in the header; to be encoded in UTF-8
Data-Format=txt: one plain reference string per line, adds new references, un-deletes ones that are re-added and were flagged as deleted
Data-Format=xml:
<refSet>
<ref>
<refString><plain reference string></refString>
<refParsed><parsed reference in MODS XML, if available></refParsed>
</ref>
<ref>...</ref>
</refSet>
response: update statistice (MIME type text/xml, encoding UTF-8), in particular the uploaded or otherwise updated references, with attributes indicating whether they were updated or alltogether newly added to RefBank:
<refSet created="number of references newly added to RefBank" updated="number of references updated, less newly created ones">
<ref id="reference ID" canonicalId="ID of canonical reference" deleted="deleted flag, true or false" createTime="UTC timestamp reference was first added to RefBank" updateTime="UTC timestamp reference was last updated" parseChecksum="MD5 hash of parsed version, if available" parseError="explanation why parsed version was rejected, if any" created="true or false, indicating whether reference was newly added to RefBank" updated="true or false, indicating whether reference existed and was updated">
<refString><plain reference string, as stored in RefBank></refString>
</ref>
<ref ...>...</ref>
</refSet>
RefBank search servlet (/RefBank/search):
GET: retrieve search form, perform search, or retrieve styled or formatted reference, depending on parameters:
id: identifier of reference, yields reference specific response if set, depending on several other parameters:
format: reference format, for use with other software
style: reference string style, for use in bibliography of a publication
isFramePage: send reference specific popup page instead of reference proper?
combinations of the id and style and format parameters return different results:
id + format=PaRsEtHeReF + isFramePage=true: reference specific popup page, with reference opened for manual parsing in embedded IFrame (used in browser, not part of API)
id + format=EdItReFsTrInG + isFramePage=true: reference specific popup page, with reference string opened for manual editing in embedded IFrame (used in browser, not part of API)
id + style or format + isFramePage=true: reference specific popup page, with reference in specified style or format showing in embedded IFrame (used in browser, not part of API)
id + style: return the reference with specified ID in the specified style (MIME type text/html, encoding UTF-8)
id + format: return the reference with specified ID in the specified data format (MIME type text/plain, encoding UTF-8)
id=MiNoRuPdATe, no style or format: return HTML form for POST callbacks from search result page (used in browser, not part of API)
canonicalStrinId: identifier of canonical representation, if set returns HTML page listing duplicate references (used in browser, not part of API)
query: full text query against reference strings
type: type of reference, only finds references with parsed version available
user: contributing user
author: query against author attribute of references, only finds references with parsed version available
title: query against title attribute of references, only finds references with parsed version available
date / year: query against year of publication attribute of references, only finds references with parsed version available (used synonymously)
origin: query against origin of references (journal + volume number, publisher or location, as well as volume title), only finds references with parsed version available
idType + idValue: query against some external identifier attribute of references (e.g. DOI or ISBN), only finds references with parsed version available
any of query, author, title, date/year, origin, or idType + idValue set: response is HTML page listing matching references (used in browser, not part of API)
no parameters at all: response is HTML page with search form (used in browser, not part of API)
POST (used in browser, not part of API): receive update callbacks from search result page
RefBank upload servlet (/RefBank/upload):
GET (used in browser, not part of API):
/RefBank/upload: retrieve upload form
/RefBank/upload/<upload-ID>/action: status info for running uploads
POST (used in browser, not part of API):
/RefBank/upload: receive text area or file upload from browser
PUT: receive upload via script:
request headers to set:
Data-Format: name of the reference data format used in request body. These are one of the formats selectable in the upload form at localhost:8080/upload. Look for the dataFormats and acceptFileExtensions arrays. This page is built dynamically so that additional formats are automatically included as support for more file types is added to RefBank.
The currently (August 2013) supported file types are:
"BibTeX" for BibTeX
"EndNote" for EndNote
"EndNoteXML" for EndNote XML
"ListTxt" for plain text
"MODS" for MODS XML
"RIS" for EndNote / RIS2
User-Name: the name of the user to credit for the contributed references
Access-Key: the upload access key; needs to match configured key for servlet to accept the upload, ignored if no key is configured
request body: references in format indicated in header
response: upload result statistics (MIME type text/plain, encoding UTF-8)
RECEIVED: <number of references received>
ERRORS: <number of references that contain errors>
CREATED: <number of references newly added to RefBank>
UPDATED: <number of references that were not newly added, but had their parsed version updated>
RefBank data index servlet (/RefBank/data):
GET: retrieve a list of reference attribute values present from parsed references in RefBank, for use as a gazetteer
parameters:
type: the type of data to retrieve
response: list of data element values of requested type (MIME type text/plain, encoding UTF-8)
type=persons: names of persons, i.e., authors and editors
type=journals: names of journals
type=publishers: names of publishers
type=origins: names of journals and publishers