-
Notifications
You must be signed in to change notification settings - Fork 4
/
metadataapi.html
374 lines (359 loc) · 16.3 KB
/
metadataapi.html
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
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
<!DOCTYPE html>
<html class="no-js" lang="en">
<head>
<title>Brain Image Library: Metadata API</title>
<meta http-equiv="x-ua-compatible" content="ie=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Raleway:400,800" />
<link rel='stylesheet' href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" />
<link rel="stylesheet" href="/css/bootstrap.css" />
<link rel="stylesheet" href="/css/styles.css" />
<link rel="stylesheet" href="/my.css" />
<script src="/js/jquery.min.js"></script>
</head>
<body class="bg">
<div class="container">
<p> </p>
</div>
<div class="container">
<!--Navigation bar-->
<div id="topmenu">
</div>
<script>
$(function(){
$("#topmenu").load("menu.html");
});
</script>
<!--end of Navigation bar-->
<div class="jumbotron">
<h1 id="Identifiers" data-id="Identifiers" style=""><span>Metadata API</span></h1>
<p><span>The </span><strong><span>Brain Image Library (BIL)</span></strong>
provides both a metadata API and web portal that uses the API to search and
return metadata and links to datasets in BIL.
The metadata API is extremely flexible and capable of full-text searching
or individual metadata fields.</p>
<p>The metadata API has two primary user-facing endpoints:
<ul>
<li><strong>query</strong> - the query endpoint will query the system and return a json document with matching entry.
Queries use GET formatted URLs, which can be pasted in a web browser, utilized at the command-line through tools such as curl, or called programmatically. Query URLs take the form of:
<br />
/query/metadatadivision?metadataelement=querystring</li><br />
<li><strong>retrieve</strong> - the retrieve endpoint will return the metadata as a json document for the given ids.
Retrieve queries can be either GET formatted urls (for retrieving metadata for a single entry) or a POST
request with a json payload. The json POST payload may be the results of an earlier query.
The basic forms of the retrieve GET url are:<br /><br />
<i>/retrieve?bildid=the_desired_id_to_retreive_metadata_for</i> <br /><br />
For example:<br /> <br />
https://api.brainimagelibrary.org/retrieve?bildid=ace-cot-pad
</li>
</ul>
<p>To make full programatic use of the Metadata API, we recommend that interested users first familiarize
yourself with <a href="newmetadatamodel.html">BIL's metadata model</a></p>
<h4>Example Results</h4>
<p>
All successful queries will return a json file, that will all have the
following json keys:
<ul>
<li>success -- true for successful queries</li>
<li>endpoint -- the endpoint used</li>
<li>message -- a user-friendly message, describing the status of the query</li>
<li>bildids -- a list of bil data ids that hold records that match the text
used in the query</li>
</ul>
There will be other keys in the json payload, based on the metadata element
and the search string. Here are a few examples:<br /><br />
<ul>
<li>Query:</li>
<a href="https://api.brainimagelibrary.org/query/contributors?affiliation=Broad">https://api.brainimagelibrary.org/query/contributors?affiliation=Broad</a>
<br />
Result:
<pre>
{
"success": "true",
"endpoint": "Contributors/affiliation",
"message": "GET success",
"affiliation": "Broad",
"bildids": [
"ace-big-pup",
"ace-big-pry",
"ace-big-pot",
"ace-big-pox",
"ace-big-pun"
]
}
</pre>
<li>Query:</li>
<a href="https://api.brainimagelibrary.org/query/image?gbytes=17.0">https://api.brainimagelibrary.org/query/image?gbytes=17.0</a>
<br />
Result:
<pre>
{
"success": "true",
"endpoint": "Image/gbytes",
"message": "GET success",
"gbytes": "17.0",
"bildids": [
"act-zip",
"ace-bay-low",
"ace-aim-gum",
"ace-ask-row",
"ace-boo-dip"
]
}
</pre>
</ul>
When one retreives an entry, the json payload returned will look like:
<ul>
<li>Query:</li>
<a href="https://api.brainimagelibrary.org/retrieve?doi=https://doi.org/10.35077/rut">https://api.brainimagelibrary.org/retrieve?doi=https://doi.org/10.35077/rut</a>
<br />
Result:
<pre>
{
"success": "true",
"endpoint": "Retrieve/doi",
"message": "GET success",
"doi": "https://doi.org/10.35077/rut",
"retjson": [
{
"Metadata": "2.0",
"Submission": {
"sheet": "57",
"collection": "1394",
"submission_uuid": "96ba8210cceceeb7",
"method": "ingest_1",
"doi": "https://doi.org/10.35077/rut"
},
"Contributors": [
{
"contributorname": "Allen Institute",
"creator": "Yes",
"contributortype": "ResearchGroup",
"nametype": "Organizational",
"nameidentifier": "",
"nameidentifierscheme": "",
"affiliation": "Allen Institute for Brain Science",
"affiliationidentifier": "https://ror.org/00dcv1019",
"affiliationidentifierscheme": "ROR"
},
{
"contributorname": "Bosiljka Tasic",
"creator": "No",
"contributortype": "ProjectLeader",
"nametype": "Personal",
"nameidentifier": "https://orcid.org/0000-0002-6861-4506",
"nameidentifierscheme": "ORCID",
"affiliation": "Allen Institute for Brain Science",
"affiliationidentifier": "https://ror.org/00dcv1019",
"affiliationidentifierscheme": "ROR"
}
],
"Funders": [
{
"fundername": "National Institutes of Health",
"funding_reference_identifier": "https://ror.org/01cwqze88",
"funding_reference_identifier_type": "ROR",
"award_number": "1-RF-1MH121274-01",
"award_title": "Cell class- or type-specific viruses for brain-wide labeling and neural circuit examination"
}
],
"Publication": [],
"Instrument": [
{
"microscopetype": "Two Photon",
"microscopemanufacturerandmodel": "TissueVision TissueCyte 1000",
"objectivename": "Zeiss 20X Plan-Apochromat",
"objectiveimmersion": "Water",
"objectivena": "1.0",
"objectivemagnification": "20X",
"detectortype": "PMT",
"detectormodel": "Hamamatsu R3896",
"illuminationtypes": "",
"illuminationwavelength": "925nm",
"detectionwavelength": "447-593nm",
"sampletemperature": "20.0"
}
],
"Specimen": [
{
"localid": "588181",
"species": "Mouse",
"ncbitaxonomy": "NCBI:txid10090",
"age": "58.0",
"ageunit": "Days",
"sex": "Female",
"genotype": "wt/wt",
"organlocalid": "1119684572.0",
"organname": "Brain",
"samplelocalid": "0539072223",
"atlas": "",
"locations": ""
}
],
"Dataset": [
{
"bildirectory": "/bil/data/96/ba/96ba8210cceceeb7/0539072223",
"title": "588181",
"socialmedia": "",
"subject": "",
"subjectscheme": "",
"rights": "Allen Institute Terms of Use, Creative Commons Attribution 4.0 International",
"rightsuri": "https://alleninstitute.org/legal/terms-use/ , https://creativecommons.org/licenses/by/4.0/",
"rightsidentifier": "CC-BY-4.0",
"dataset_image": "https://alleninstitute.org/media/filer_public_thumbnails/filer_public/2e/6e/2e6e35a2-a82e-4e1c-af3d-4e95e43d3baf/logo_bs_header.png__220x220_q75_subsampling-2.jpg",
"generalmodality": "population imaging",
"technique": "enhancer virus labeling",
"other": "",
"abstract": "This is a series of serial two-photon images of whole mouse brain to characterize cell populations for the purpose of evaluating the specificity of newly created enhancer elements",
"methods": "",
"technicalinfo": "",
"doi": "https://doi.org/10.35077/rut",
"dataset_size": "None"
}
],
"Assets": [
{
"bildid": "rut",
"bildoi": "https://doi.org/10.35077/rut",
"manifestfile": "https://download.brainimagelibrary.org/inventory/248f1b89-d78f-575c-88a4-32ad314a4a6e.json"
}
],
"Image": [
{
"xaxis": "left-to-right",
"obliquexdim1": "",
"obliquexdim2": "",
"obliquexdim3": "",
"yaxis": "superior-to-inferior",
"obliqueydim1": "",
"obliqueydim2": "",
"obliqueydim3": "",
"zaxis": "posterior-to-anterior",
"obliquezdim1": "",
"obliquezdim2": "",
"obliquezdim3": "",
"landmarkname": "",
"landmarkx": "",
"landmarky": "",
"landmarkz": "",
"number": "1,2,3,red,green,blue",
"displaycolor": "(1.0,0.0,0.0),(0.0,1.0,0.0),(0.0,0.0,1.0)",
"representation": "neurite",
"flurophore": "CH1(background fluorescence) CH2(GFP) CH3(background fluorescence)",
"stepsizex": "0.35",
"stepsizey": "0.35",
"stepsizez": "100.0",
"stepsizet": "",
"channels": "3.0",
"slices": "140.0",
"z": "1.0",
"xsize": "40000.0",
"ysize": "30000.0",
"zsize": "1.0",
"gbytes": "",
"files": "",
"dimensionorder": ""
}
]
}
]
}
</pre>
</ul>
Note that if one retreives MULTIPLE entries via a PUT request, there will be
multiple objects returned in the retjson array
<br /><br />
<h4>Errors</h4>
When the API detects an error it will return a json message indicating the
error. typical keys returned in the json payload include:
<ul>
<li>success - with an error, this will be false.</li>
<li>endpoint -- the endpoint used.</li>
<li>message -- a user-friendly message, describing why the error happened.</li>
</ul>
Here is an example (using CURL) if a POST was issued instead of GET:
<ul>
<li>Query:</li>
curl -X POST http://localhost:8100/query/contributors?affiliation=Broad
<br />
Result:
<pre>
{
"success": "false",
"endpoint": "Contributors",
"message": "POST method not allowed"
}
</pre></ul>
Handling Partial Sucesss/ Partial Failure: This currently will only happen if one uses the /retreive endpoint with a post
request. In such cases keys:
<ul>
<li>success -- this will be "true" NOT "false".</li>
<li>message -- will state that the POST was partially successful.</li>
<li>status -- (key,value)- will be "true" for ID's returned in
"retjson", otherwise "false"</li>
<li>retjson -- will only contain metadata for the entries found.</li>
</ul>
Here is a brief example of what the beginning of the returned json document
will look like:
<pre>
{
"success": "true",
"endpoint": "Retrieve",
"message": "POST partially successful, some entries retreived",
"status": {
"act-zip": true,
"ace-bay-low": true,
"ace-aim-gum": false,
"ace-ask-row": false,
"ace-boo-dip": true
},
"retjson": [ ... ]
}
</pre>
<h4> Additional Examples</h4>
Some examples using the web browser: <br /><br />
<a href="https://api.brainimagelibrary.org/query/fulltext?text=broad">https://api.brainimagelibrary.org/query/fulltext?text=broad</a>
<br /><a href="https://api.brainimagelibrary.org/query/funders?award_number=1-RF1-MH-124598-01">https://api.brainimagelibrary.org/query/funders?award_number=1-RF1-MH-124598-01</a>
<br /><a href="https://api.brainimagelibrary.org/query/submission?doi=rut">https://api.brainimagelibrary.org/query/submission?doi=rut</a>
<br /><a href="https://api.brainimagelibrary.org/query/contributors?affiliation=Broad">https://api.brainimagelibrary.org/query/contributors?affiliation=Broad</a>
<br /><a href="https://api.brainimagelibrary.org/query/contributors?creator=Yes">https://api.brainimagelibrary.org/query/contributors?creator=Yes</a>
<br /><a href="https://api.brainimagelibrary.org/query/instrument?microscopetype=upright">https://api.brainimagelibrary.org/query/instrument?microscopetype=upright</a>
<br /><a href="https://api.brainimagelibrary.org/query/instrument?objectivename=olympus">https://api.brainimagelibrary.org/query/instrument?objectivename=olympus</a>
<br /><a href="https://api.brainimagelibrary.org/query/specimen?localid=f024">https://api.brainimagelibrary.org/query/specimen?localid=f024</a>
<br /><a href="https://api.brainimagelibrary.org/query/dataset?title=mouse">https://api.brainimagelibrary.org/query/dataset?title=mouse</a>
<br /><a href="https://api.brainimagelibrary.org/query/image?gbytes=17.0">https://api.brainimagelibrary.org/query/image?gbytes=17.0</a>
<br /><a href="https://api.brainimagelibrary.org/query/publication?relatedidentifier=doi">https://api.brainimagelibrary.org/query/publication?relatedidentifier=doi</a>
<br /><a href="https://api.brainimagelibrary.org/retrieve?bildid=rut">https://api.brainimagelibrary.org/retrieve?bildid=rut</a>
<br /><a href="https://api.brainimagelibrary.org/retrieve?doi=https://doi.org/10.35077/rut">https://api.brainimagelibrary.org/retrieve?doi=https://doi.org/10.35077/rut</a>
<br /><br />
Some examples accessing the API using curl are shown below: </br></br>
<pre>
curl -k -X GET 'https://api.brainimagelibrary.org/query/fulltext?text=broad'
curl -k -X GET 'https://api.brainimagelibrary.org/query/funders?award_number=1-RF1-MH-124598-01'
curl -k -X GET 'https://api.brainimagelibrary.org/query/submission?doi=rut'
curl -k -X GET 'https://api.brainimagelibrary.org/query/contributors?affiliation=Broad'
curl -k -X GET 'https://api.brainimagelibrary.org/query/contributors?creator=Yes'
curl -k -X GET 'https://api.brainimagelibrary.org/query/instrument?microscopetype=upright'
curl -k -X GET 'https://api.brainimagelibrary.org/query/instrument?objectivename=olympus'
curl -k -X GET 'https://api.brainimagelibrary.org/query/specimen?localid=f024'
curl -k -X GET 'https://api.brainimagelibrary.org/query/dataset?title=mouse'
curl -k -X GET 'https://api.brainimagelibrary.org/query/image?gbytes=17.0'
curl -k -X GET 'https://api.brainimagelibrary.org/query/publication?relatedidentifier=doi'
curl -k -X GET 'https://api.brainimagelibrary.org/retrieve?bildid=rut'
curl -k -X GET 'https://api.brainimagelibrary.org/retrieve?doi=https://doi.org/10.35077/rut'
</pre>
</div>
<!--Bottom Footer -->
<div id="bottomfooter">
</div>
<script>
$(function(){
$("#bottomfooter").load("footer.html");
});
</script>
<!--end of bottomfooter-->
<script src="/js/jquery.min.js"></script>
<script src="/js/popper.min.js"></script>
<script src="/js/bootstrap.min.js"></script>
</body>
</html>