API for Server Data Queries: Difference between revisions

From Eterna Wiki

m (Removed � from noti_count_for_user query line)
m (Update formatting)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<p>The EteRNA servers implement a <a href="http://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a> API for much of the data behind both the game and lab.&nbsp; This data is available to both in-game scripts and browser-based tools.</p>
__TOC__<p>The Eterna servers implement a [[wikipedia:Representational_state_transfer|RESTful]] API for much of the data behind both the game and lab. This data is available to both in-game scripts and browser-based tools.</p>
<p>__TOC__</p>
 
<p>&nbsp;</p>
== Overview ==
<p>==Overview==</p>
<p>Queries can be submitted directly from any browser (by specifying the URL in the browser's address bar), from an application running in the browser, or from the in-game scrpting engine. When issued from a browser, the query takes the form of a URL.&nbsp;When issued from the in-game scrpting engine, it takes the form of a call to the function AjaxManager.querySync.</p>
<p>Queries can be submitted directly from any browser (by specifying the URL in the browser's address bar), from an application running in the browser, or from the in-game scrpting engine.&nbsp; When issued from a browser, the query takes the form of a URL.&nbsp; When issued from the in-game scrpting engine, it takes the form of a call to the function AjaxManager.querySync.</p>
 
<p>===Examples===</p>
=== Examples ===
<p>====From a browser====</p>
 
==== From a browser ====
<ul>
<ul>
<li><a href="http://eterna.cmu.edu/get/?type=lab&amp;nid=2857430">http://eterna.cmu.edu/get/?type=lab&amp;nid=2857430</a> requests metadata about the lab with ID 2857430.</li>
<li>https://eternagame.org/get/?type=lab&amp;nid=2857430 requests metadata about the lab with ID 2857430.</li>
</ul>
</ul>
<p>====From in-game scripts====</p>
 
==== From in-game scripts ====
<ul>
<ul>
<li><span style="font-family: courier new,courier;">AjaxManager.querySync("GET", Application.GET_URI, {type:lab, nid:2857430})</span> requests data about the lab with ID 2857430.</li>
<li><span style="font-family: courier new,courier;">AjaxManager.querySync("GET", Application.GET_URI, {type:lab, nid:2857430})</span> requests data about the lab with ID 2857430.</li>
</ul>
</ul>
<p>==Query types==</p>
 
<p>===Query type active_labs===</p>
== Query types ==
<p>This is a deprecated API for getting information about active labs.&nbsp; The recommended query is now type=active_projects.</p>
 
<p>===Query type active_projects===</p>
=== Query type active_labs ===
<p>====Other parameters====</p>
<p>This is a deprecated API for getting information about active labs.&nbsp;The recommended query is now <code>type=active_projects</code>.</p>
 
=== Query type active_projects ===
 
==== Other parameters ====
<ul>
<ul>
<li>start - the first index of the array of labs (deafults to 0).&nbsp; Together with the size parameter, this is used to break the list over multiple plages.</li>
<li>start - the first index of the array of labs (deafults to 0). Together with the size parameter, this is used to break the list over multiple places.</li>
<li>size - the number of active labs to return</li>
<li>size - the number of active labs to return</li>
</ul>
</ul>
<p>====Information returned====</p>
 
==== Information returned ====
<p>This returns information about the currently active labs. The information includes</p>
<p>This returns information about the currently active labs. The information includes</p>
<ul>
<ul>
Line 29: Line 36:
<li>Lab founder</li>
<li>Lab founder</li>
</ul>
</ul>
<p>This query does <span style="text-decoration: underline;">not</span> include anything about the lab's submissions.&nbsp; To get information about submissions to an active lab, use the type-solutions query for each lab  id in this list.</p>
<p>This query does <span style="text-decoration: underline;">not</span> include anything about the lab's submissions. To get information about submissions to an active lab, use the type-solutions query for each lab  id in this list.</p>
<p>For more details, see [[/Server Queries: type=active_projects|Server Queries: type=active_projects]].</p>
<p>For more details, see [[/Server Queries: type=active_projects|Server Queries: type=active_projects]].</p>
<p>===Query type achievement_roadmap===</p>
 
<p>===Query type blogs===</p>
=== Query type achievement_roadmap ===
<p>===Query type blogslist===</p>
 
<p>===Query type follows===</p>
=== Query type blogs ===
<p>===Query type group===</p>
 
<p>===Query type groups===</p>
=== Query type blogslist ===
<p>===Query type lab===</p>
 
<p>====Other parameters====</p>
=== Query type follows ===
 
=== Query type get_labs_for_my_lab_cards ===
 
=== Query type group ===
 
=== Query type groups ===
 
=== Query type lab ===
 
==== Other parameters ====
<ul>
<ul>
<li>nid - the lab ID (required)</li>
<li>nid - the lab ID (required)</li>
</ul>
</ul>
<p>====Information returned====</p>
 
<p>This returns meta information about the lab.&nbsp; It's content is largely determined by what information appears on the UI's main page for the lab, e.g. <a href="http://eterna.cmu.edu/web/lab/3376133/">http://eterna.cmu.edu/web/lab/3376133/</a>.&nbsp; This includes the</p>
==== Information returned ====
<p>This returns meta information about the lab.&nbsp;It's content is largely determined by what information appears on the UI's main page for the lab, e.g. https://eternagame.org/web/lab/3376133/<nowiki/>.&nbsp;This includes the</p>
<ul>
<ul>
<li>Title</li>
<li>Title</li>
Line 54: Line 72:
</ul>
</ul>
<p>For more details, see [[/Server Queries: type=lab|Server Queries: type=lab]].</p>
<p>For more details, see [[/Server Queries: type=lab|Server Queries: type=lab]].</p>
<p>===Query type labs===</p>
 
<p>===Query type <span>lab_synthesized_results</span>===</p>
=== Query type labs ===
<p>This is the query the HTML browser uses to get synthesis results. &nbsp;The Flash browser continues to use the solutions query type.</p>
 
<p>This query makes heavy use of mixed type arrays (in lieu of objects), so it is much less self-documenting than most. &nbsp;Presumably this was done to reduce the size of the results.</p>
=== Query type <span>lab_synthesized_results</span> ===
<p>====Other parameters====</p>
<p>This is the query the HTML browser uses to get synthesis results. The Flash browser continues to use the solutions query type.</p>
<p>This query makes heavy use of mixed type arrays (in lieu of objects), so it is much less self-documenting than most. Presumably this was done to reduce the size of the results.</p>
 
==== Other parameters ====
<ul>
<ul>
<li>nid - the lab ID (required)</li>
<li>nid - the lab ID (required)</li>
</ul>
</ul>
<p>====Information returned====</p>
 
==== Information returned ====
<p>For more details, see [[/Server Queries: type=lab_synthesized_results|Server Queries: type=<span>lab_synthesized_results</span>]].</p>
<p>For more details, see [[/Server Queries: type=lab_synthesized_results|Server Queries: type=<span>lab_synthesized_results</span>]].</p>
<p>===Query type me===</p>
 
<p>===Query type my_user===</p>
=== Query type me ===
<p>===Query type my_groups===</p>
 
<p>===Query type newsfeed===</p>
=== Query type my_user ===
<p>===Query type newslist===</p>
 
<p>===Query type noti_count_for_user===</p>
=== Query type my_groups ===
<p>===Query type past_labs (Deprecated)===</p>
 
<p>This query type no longer functions properly for new labs. Use query type labs instead</p>
=== Query type newsfeed ===
 
=== Query type newslist ===
 
=== Query type noti_count_for_user ===
 
=== Query type past_labs (Deprecated) ===
<p>This query type no longer functions properly for new labs. Use [[#Query_type_labs|query type labs]] instead</p>
<ul>
<ul>
<li>size - number of labs to include (required to get details)</li>
<li>size - number of labs to include (required to get details)</li>
<li>start - number of labs to skip before returning the size (above)</li>
<li>start - number of labs to skip before returning the size (above)</li>
</ul>
</ul>
<p>===Query type past_projects===</p>
 
=== Query type past_projects ===
<ul>
<ul>
<li>size - number of projects to include (required to get details)</li>
<li>size - number of projects to include (required to get details)</li>
Line 82: Line 112:
</ul>
</ul>
<p>For more details, see [[/Server Queries: type=past_projects|Server Queries: type=past_projects]].</p>
<p>For more details, see [[/Server Queries: type=past_projects|Server Queries: type=past_projects]].</p>
<p>===Query type pending_labs===</p>
 
<p>===Query type project===</p>
=== Query type pending_labs ===
<p>====Other parameters====</p>
 
=== Query type project ===
 
==== Other parameters ====
<ul>
<ul>
<li>nid - the project ID (required) - Note that projects were introduced with cloud lab 9, and the project ID is not the same as the lab ID, even if there is only one lab in a project.&nbsp; If the nid specified here is for an earlier lab, the query will be reinterpreted to return the same results that the type=lab query does.&nbsp; (Verify this!)</li>
<li>nid - the project ID (required) - Note that projects were introduced with cloud lab 9, and the project ID is not the same as the lab ID, even if there is only one lab in a project.&nbsp;If the nid specified here is for an earlier lab, the query will be reinterpreted to return the same results that the type=lab query does.&nbsp; (Verify this!)</li>
</ul>
</ul>
<p>====Information returned====</p>
 
<p>This returns meta information about the project.&nbsp; Its content is largely determined by what information appears on the UI's main page for the project , e.g. <a href="http://eterna.cmu.edu/web/lab/3376330/">http://eterna.cmu.edu/web/lab/3376330/</a>, including meta&nbsp; information on labs within the project.&nbsp; But there is is less informatation about the constituent labs than for a type=lab query.</p>
==== Information returned ====
<p>This returns meta information about the project.&nbsp;Its content is largely determined by what information appears on the UI's main page for the project, e.g. https://eternagame.org/web/lab/3376330/, including meta information on labs within the project.&nbsp;But there is is less informatation about the constituent labs than for a type=lab query.</p>
<ul>
<ul>
<li>Title of the project</li>
<li>Title of the project</li>
Line 101: Line 135:
</ul>
</ul>
<p>For more details, see [[/Server Queries: type=project|Server Queries: type=project]].</p>
<p>For more details, see [[/Server Queries: type=project|Server Queries: type=project]].</p>
<p>===Query type puzzle===</p>
 
<p>===Query type puzzles===</p>
=== Query type puzzle ===
<p>===Query type recents===</p>
 
<p>===Query type script===</p>
=== Query type puzzles ===
<p>===Query type solution_info===</p>
 
<p>===Query type solutions===</p>
=== Query type recents ===
<p>===Query type user===</p>
 
<p>===Query type users===</p>
=== Query type script ===
<p>====Other parameters====</p>
 
=== Query type side_project_roadmap ===
 
=== Query type solution_info ===
 
=== Query type solutions ===
 
==== Other parameters ====
<ul>
<ul>
<li>search - string that will be used to find user name(s). &nbsp;All user names that contain the search string will be returned. &nbsp;Matching is case insensitive.</li>
<li>puznid - the puzzle ID (required)</li>
</ul>
</ul>
<p>====Information returned====</p>
 
<p>An array or user objects is returned. &nbsp;The members of the user object are</p>
=== Query type user ===
 
=== Query type users ===
 
==== Other parameters ====
<ul>
<li>search - string that will be used to find user name(s).&nbsp;All user names that contain the search string will be returned.&nbsp;Matching is case insensitive.</li>
</ul>
 
==== Information returned ====
<p>An array or user objects is returned. The members of the user object are</p>
<ul>
<ul>
<li><span>uid</span></li>
<li><span>uid</span></li>
Line 123: Line 174:
<li><span>picture</span></li>
<li><span>picture</span></li>
</ul>
</ul>
<p>===Query type votes===</p>
 
<p>==Issues surrounding recent changes==</p>
=== Query type votes ===
<p>For the moment,&nbsp; this is focused on documenting the 9/26 changes that broke a bunch of existing scripts.</p>
 
== Issues surrounding recent changes ==
<p>For the moment,&nbsp;this is focused on documenting the 9/26/13 changes that broke a bunch of existing scripts.</p>
<p><strong>Update: Justin says he'll return the old API, to preserve compatibility with existing scripts.&nbsp; Thanks, Justin!</strong></p>
<p><strong>Update: Justin says he'll return the old API, to preserve compatibility with existing scripts.&nbsp; Thanks, Justin!</strong></p>
<p>Friday (5:50 PM PDT) update: My Data Mining Tool, which was broken by the change to the type=lab query, now works again.&nbsp; But I think Justin was probably especially careful about fixing the queries it uses.<strong>&nbsp; I advise anyone reading this to test any scripts they really care about, and if it is still broken, post here.&nbsp; Please describe the query URL, and what about the JSON is missing.</strong></p>
<p>Friday (5:50 PM PDT) update: My Data Mining Tool, which was broken by the change to the type=lab query, now works again.&nbsp; But I think Justin was probably especially careful about fixing the queries it uses.<strong>&nbsp; I advise anyone reading this to test any scripts they really care about, and if it is still broken, post here.&nbsp; Please describe the query URL, and what about the JSON is missing.</strong></p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 01:30, 28 September 2013 (UTC)</p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 01:30, 28 September 2013 (UTC)</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>My favorite script by Stlne is broken. The one that states how many votes and design slots I have left in a lab. Here is its URL: http://eterna.cmu.edu/web/script/3126111/ and here is the message I get back: Return : jsonOut.data.labs is undefined</p>
<p>My favorite script by Stlne is broken. The one that states how many votes and design slots I have left in a lab. Here is its URL: https://eternagame.org/web/script/3126111/ and here is the message I get back: Return : jsonOut.data.labs is undefined</p>
<p><span id="docs-internal-guid-11878caa-7a0b-be1d-9337-e321c9b11e1e" style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">-- [[User:Eli Fisker|Eli Fisker]] ([[User talk:Eli Fisker|talk]]) 16:42, 2 October 2013 (UTC)</span></p>
<p><span id="docs-internal-guid-11878caa-7a0b-be1d-9337-e321c9b11e1e" style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">-- [[User:Eli Fisker|Eli Fisker]] ([[User talk:Eli Fisker|talk]]) 16:42, 2 October 2013 (UTC)</span></p>
<p><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">I confirmed this has been fixed.</span></p>
<p><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">I confirmed this has been fixed.</span></p>
Line 138: Line 191:
<p id="docs-internal-guid-11878caa-c301-4949-c4e7-d3fa3b925ccb" style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">-- [[User:Eli Fisker|Eli Fisker]] ([[User talk:Eli Fisker|talk]]) 20:46, 16 October 2013 (UTC)</span></p>
<p id="docs-internal-guid-11878caa-c301-4949-c4e7-d3fa3b925ccb" style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">-- [[User:Eli Fisker|Eli Fisker]] ([[User talk:Eli Fisker|talk]]) 20:46, 16 October 2013 (UTC)</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">----</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">----</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">Agreed; this was my mistake. The UI is generating the same query, "</span>http://eterna.cmu.edu//get/?type=active_labs<span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">", as the script, but somehow the UI gets the right answer.&nbsp; Must be something in the headers.&nbsp; In any case, Justin is aware of it now.</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">Agreed; this was my mistake. The UI is generating the same query, "</span>https://eternagame.org//get/?type=active_labs<span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">", as the script, but somehow the UI gets the right answer.&nbsp; Must be something in the headers.&nbsp; In any case, Justin is aware of it now.</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 23:49, 16 October 2013 (UTC)<br /></span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 23:49, 16 October 2013 (UTC)<br /></span></p>
<p>&nbsp;</p>
<p>&nbsp;</p>
Line 145: Line 198:
<ol>
<ol>
<li>The thumbnail images have been moved to Amazon's S3 service.&nbsp; The thumbnails don't exist at their old location.&nbsp; This breaks scripts that displayed the thumbnails, like my took that creates the list of past labs here on the wiki.&nbsp; But moving them to Amazon seems good, so I'm just going to update that script.<br /><strong>Update: To my pleasant surprise, the thumbnails are back at the old URL on the Eterna servers, as well as thei new location in the Amazon cloud.&nbsp; Not only that, but thumbnails for the newest labs have been added, too.&nbsp; So I don't have to update the script right away.&nbsp; For me, this is striking evidence that Eterna really is serious about supporting player-led developments.&nbsp; A big thanks to the Eterna devs in general and (presumably) to Justin in particular.</strong></li>
<li>The thumbnail images have been moved to Amazon's S3 service.&nbsp; The thumbnails don't exist at their old location.&nbsp; This breaks scripts that displayed the thumbnails, like my took that creates the list of past labs here on the wiki.&nbsp; But moving them to Amazon seems good, so I'm just going to update that script.<br /><strong>Update: To my pleasant surprise, the thumbnails are back at the old URL on the Eterna servers, as well as thei new location in the Amazon cloud.&nbsp; Not only that, but thumbnails for the newest labs have been added, too.&nbsp; So I don't have to update the script right away.&nbsp; For me, this is striking evidence that Eterna really is serious about supporting player-led developments.&nbsp; A big thanks to the Eterna devs in general and (presumably) to Justin in particular.</strong></li>
<li>The format of the type=past-labs query (e.g. <a href="http://eterna.cmu.edu/get/?type=past_labs&amp;skip=0&amp;size=21">http://eterna.cmu.edu/get/?type=past_labs&amp;skip=0&amp;size=21</a> response has changed.&nbsp; It may well be completely backward compatible; I'm not sure because I don't have a complete record of what it was.&nbsp; But as it stands now, a solution has a field named "puzzles", which is an array of objects.&nbsp; Each element of the array is an object which has a field also called "puzzles", which is also an array.&nbsp; Each element of this array is a nid which seems to correspond to a secondary structure, because the query "<span style="color: #222222; font-family: Consolas, 'Lucida Console', monospace; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: left; text-indent: 0px; text-transform: none; white-space: pre-wrap; widows: auto; word-spacing: 0px; background-color: #ffffff; display: inline !important; float: none;">https://s3.amazonaws.com/eterna/puzzle_mid_thumbnails/thumbnail&lt;nid&gt;.png" returns a thumbnail image of the target structure for that lab. I think this new level of indirection is there to support labs that allow sequences with differernt lengths and target structures. The reproducibility lab is one example, but I remember Rhiju talking about supporting this, long before the reproducibility lab came into being.</span></li>
<li>The format of the type=past-labs query (e.g. https://eternagame.org/get/?type=past_labs&amp;skip=0&amp;size=21 response has changed.&nbsp; It may well be completely backward compatible; I'm not sure because I don't have a complete record of what it was.&nbsp; But as it stands now, a solution has a field named "puzzles", which is an array of objects.&nbsp; Each element of the array is an object which has a field also called "puzzles", which is also an array.&nbsp; Each element of this array is a nid which seems to correspond to a secondary structure, because the query "<span style="color: #222222; font-family: Consolas, 'Lucida Console', monospace; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: left; text-indent: 0px; text-transform: none; white-space: pre-wrap; widows: auto; word-spacing: 0px; background-color: #ffffff; display: inline !important; float: none;">https://s3.amazonaws.com/eterna/puzzle_mid_thumbnails/thumbnail&lt;nid&gt;.png" returns a thumbnail image of the target structure for that lab. I think this new level of indirection is there to support labs that allow sequences with differernt lengths and target structures. The reproducibility lab is one example, but I remember Rhiju talking about supporting this, long before the reproducibility lab came into being.</span></li>
</ol>
</ol>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 01:30, 28 September 2013 (UTC)</p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 01:30, 28 September 2013 (UTC)</p>
Line 152: Line 205:
<p>Apparently Justin restored the behavior of the lab query for existing labs, but didn't cary that over to new labs.&nbsp; A query for a new lab returns</p>
<p>Apparently Justin restored the behavior of the lab query for existing labs, but didn't cary that over to new labs.&nbsp; A query for a new lab returns</p>
<p><span style="font-family: courier new,courier;">{"data":{"lab":null,"comments":[],"supercomments":[],"num_synthesized":0,"follow":[],"num_slots":false,"sum_picks":null,"num_solutions":"0","my_votes":null,"uid":"57675"},"memcache":true}</span></p>
<p><span style="font-family: courier new,courier;">{"data":{"lab":null,"comments":[],"supercomments":[],"num_synthesized":0,"follow":[],"num_slots":false,"sum_picks":null,"num_solutions":"0","my_votes":null,"uid":"57675"},"memcache":true}</span></p>
<p>So any existing scripts that use the lab query are still broken for new labs.&nbsp; I'll raise this issue with Justin.</p>
<p>So any existing scripts that use the lab query are still broken for new labs. I'll raise this issue with Justin.</p>
<p><strong>Resolution</strong>: Justin pointed out that I was incorrect; the lab query for the latest round returns the same results it used to.&nbsp; The cause of my confusion is that the in-game URLs can be misleading.&nbsp; If you go to the past labs page and choose the Reprodicibility Lab, you'r be taken to the URL http://eterna.cmu.edu/web/lab/3376330/.&nbsp; But 3376330 is <span style="text-decoration: underline;">not</span> the lab ID; it is the project (a new construct)&nbsp; ID.&nbsp; To determine the lab ID, you have to click through to the browse page, whose URL is http://eterna.cmu.edu/web/browse/3293294/. Here we see the lab ID, and if you use that in a type=lab GET query, you'll get the results you expect.</p>
<p><strong>Resolution</strong>: Justin pointed out that I was incorrect; the lab query for the latest round returns the same results it used to.&nbsp;The cause of my confusion is that the in-game URLs can be misleading. If you go to the past labs page and choose the Reprodicibility Lab, you'r be taken to the URL https://eternagame.org/web/lab/3376330/. But 3376330 is <span style="text-decoration: underline;">not</span> the lab ID; it is the project (a new construct)&nbsp; ID.&nbsp; To determine the lab ID, you have to click through to the browse page, whose URL is https://eternagame.org/web/browse/3293294/. Here we see the lab ID, and if you use that in a type=lab GET query, you'll get the results you expect.</p>
<p>Hopefully the project/lab terminolgy will get straigthened out.</p>
<p>Hopefully the project/lab terminolgy will get straigthened out.</p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 23:45, 30 September 2013 (UTC)</p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 23:45, 30 September 2013 (UTC)</p>
<p>----</p>
<p>----</p>
<h3>Missing Semicirle - 2 bends and Semicircle - 5 bends in past labs.</h3>
<h3>Missing Semicirle - 2 bends and Semicircle - 5 bends in past labs.</h3>
<p>This is a strange one.&nbsp; I don't know that it is related to the recent server changes, but I'll note it here.</p>
<p>This is a strange one. I don't know that it is related to the recent server changes, but I'll note it here.</p>
<p>The two labs<em> Semicircle - 2 bends</em> and <em>Semicircle - 5 bends</em>, which were part of Cloud Lab 8, have disappeared from the past_labs query and replaced by <em> Semicircle - 3 bends</em> and <em>Semicircle - 4 bends</em>, which were part of Cloud Lab 9.&nbsp; The easiest way to confirm this is to look at the <a href="/wiki/index.php5?title=List_of_EteRNA_Labs&amp;diff=2932&amp;oldid=2839">most recent diff</a> for the list of labs.&nbsp; Search for "2 bends".&nbsp; I verified that the GET query for past_labs isn't returning them, but the queries for solutions and lab still do.</p>
<p>The two labs<em> Semicircle - 2 bends</em> and <em>Semicircle - 5 bends</em>, which were part of Cloud Lab 8, have disappeared from the past_labs query and replaced by <em> Semicircle - 3 bends</em> and <em>Semicircle - 4 bends</em>, which were part of Cloud Lab 9. The easiest way to confirm this is to look at the [[List of Eterna Labs|most recent diff]] for the list of labs.&nbsp; Search for "2 bends". I verified that the GET query for past_labs isn't returning them, but the queries for solutions and lab still do.</p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 01:57, 3 October 2013 (UTC)</p>
<p>[[User:Omei|Omei]] ([[User talk:Omei|talk]]) 01:57, 3 October 2013 (UTC)</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>These two labs are under [http://eterna.cmu.edu/web/labs/proposed/?skip=0&amp;size=21&amp;search=Semi&amp;sort=date Proposed labs] for now, as the new button for open 2 round was so easy to hit that several lab makers hit it by accident. Justin has disabled the option for now.</p>
<p>These two labs are under [https://eternagame.org/web/labs/proposed/?skip=0&amp;size=21&amp;search=Semi&amp;sort=date Proposed labs] for now, as the new button for open 2 round was so easy to hit that several lab makers hit it by accident. Justin has disabled the option for now.</p>
<p id="docs-internal-guid-11878caa-c301-4949-c4e7-d3fa3b925ccb" style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">-- [[User:Eli Fisker|Eli Fisker]] ([[User talk:Eli Fisker|talk]]) 20:46, 16 October 2013 (UTC)</span></p>
<p id="docs-internal-guid-11878caa-c301-4949-c4e7-d3fa3b925ccb" style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">-- [[User:Eli Fisker|Eli Fisker]] ([[User talk:Eli Fisker|talk]]) 20:46, 16 October 2013 (UTC)</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">----</span></p>
<p style="line-height: 1.2272727272727273; margin-top: 0pt; margin-bottom: 0pt;" dir="ltr"><span style="font-size: 15px; font-family: Arial; color: #000000; background-color: #ffffff; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline;">----</span></p>
<p>&nbsp;</p>
[[Category:Eterna Development]]
<p>&nbsp;</p>
<p><strong><br /></strong></p>

Latest revision as of 01:30, 29 June 2022

The Eterna servers implement a RESTful API for much of the data behind both the game and lab. This data is available to both in-game scripts and browser-based tools.

Overview

Queries can be submitted directly from any browser (by specifying the URL in the browser's address bar), from an application running in the browser, or from the in-game scrpting engine. When issued from a browser, the query takes the form of a URL. When issued from the in-game scrpting engine, it takes the form of a call to the function AjaxManager.querySync.

Examples

From a browser

From in-game scripts

  • AjaxManager.querySync("GET", Application.GET_URI, {type:lab, nid:2857430}) requests data about the lab with ID 2857430.

Query types

Query type active_labs

This is a deprecated API for getting information about active labs. The recommended query is now type=active_projects.

Query type active_projects

Other parameters

  • start - the first index of the array of labs (deafults to 0). Together with the size parameter, this is used to break the list over multiple places.
  • size - the number of active labs to return

Information returned

This returns information about the currently active labs. The information includes

  • Lab ID (called nid here)
  • Lab Ddscription (called body)
  • Lab founder

This query does not include anything about the lab's submissions. To get information about submissions to an active lab, use the type-solutions query for each lab id in this list.

For more details, see Server Queries: type=active_projects.

Query type achievement_roadmap

Query type blogs

Query type blogslist

Query type follows

Query type get_labs_for_my_lab_cards

Query type group

Query type groups

Query type lab

Other parameters

  • nid - the lab ID (required)

Information returned

This returns meta information about the lab. It's content is largely determined by what information appears on the UI's main page for the lab, e.g. https://eternagame.org/web/lab/3376133/. This includes the

  • Title
  • Description
  • Target structure
  • Comments
  • Number of submissions
  • Number of syntheses, if any
  • Summary of the highest scoring syntheses

For more details, see Server Queries: type=lab.

Query type labs

Query type lab_synthesized_results

This is the query the HTML browser uses to get synthesis results. The Flash browser continues to use the solutions query type.

This query makes heavy use of mixed type arrays (in lieu of objects), so it is much less self-documenting than most. Presumably this was done to reduce the size of the results.

Other parameters

  • nid - the lab ID (required)

Information returned

For more details, see Server Queries: type=lab_synthesized_results.

Query type me

Query type my_user

Query type my_groups

Query type newsfeed

Query type newslist

Query type noti_count_for_user

Query type past_labs (Deprecated)

This query type no longer functions properly for new labs. Use query type labs instead

  • size - number of labs to include (required to get details)
  • start - number of labs to skip before returning the size (above)

Query type past_projects

  • size - number of projects to include (required to get details)
  • start - number of projects to skip before returning the size (above)

For more details, see Server Queries: type=past_projects.

Query type pending_labs

Query type project

Other parameters

  • nid - the project ID (required) - Note that projects were introduced with cloud lab 9, and the project ID is not the same as the lab ID, even if there is only one lab in a project. If the nid specified here is for an earlier lab, the query will be reinterpreted to return the same results that the type=lab query does.  (Verify this!)

Information returned

This returns meta information about the project. Its content is largely determined by what information appears on the UI's main page for the project, e.g. https://eternagame.org/web/lab/3376330/, including meta information on labs within the project. But there is is less informatation about the constituent labs than for a type=lab query.

  • Title of the project
  • Description of the project
  • For each lab in the project
    • Number of submissions
    • Number of syntheses, if any

For more details, see Server Queries: type=project.

Query type puzzle

Query type puzzles

Query type recents

Query type script

Query type side_project_roadmap

Query type solution_info

Query type solutions

Other parameters

  • puznid - the puzzle ID (required)

Query type user

Query type users

Other parameters

  • search - string that will be used to find user name(s). All user names that contain the search string will be returned. Matching is case insensitive.

Information returned

An array or user objects is returned. The members of the user object are

  • uid
  • name
  • points
  • synths
  • created
  • picture

Query type votes

Issues surrounding recent changes

For the moment, this is focused on documenting the 9/26/13 changes that broke a bunch of existing scripts.

Update: Justin says he'll return the old API, to preserve compatibility with existing scripts.  Thanks, Justin!

Friday (5:50 PM PDT) update: My Data Mining Tool, which was broken by the change to the type=lab query, now works again.  But I think Justin was probably especially careful about fixing the queries it uses.  I advise anyone reading this to test any scripts they really care about, and if it is still broken, post here.  Please describe the query URL, and what about the JSON is missing.

Omei (talk) 01:30, 28 September 2013 (UTC)

 

My favorite script by Stlne is broken. The one that states how many votes and design slots I have left in a lab. Here is its URL: https://eternagame.org/web/script/3126111/ and here is the message I get back: Return : jsonOut.data.labs is undefined

-- Eli Fisker (talk) 16:42, 2 October 2013 (UTC)

I confirmed this has been fixed.

Omei (talk) 18:50, 16 October 2013 (UTC)

---

The script is now running, but except for the top lab in the pic I have linked in here, it is stuck in time, only showing past rounds labs

-- Eli Fisker (talk) 20:46, 16 October 2013 (UTC)

----

Agreed; this was my mistake. The UI is generating the same query, "https://eternagame.org//get/?type=active_labs", as the script, but somehow the UI gets the right answer.  Must be something in the headers.  In any case, Justin is aware of it now.

Omei (talk) 23:49, 16 October 2013 (UTC)

 

type=past-labs: New fields are needed to access the thumbnail images (change)

I note two related changes here, but I wouldn't consider asking Justin t change it for my scripts.  They seem like a reasonable step in moving forward.

  1. The thumbnail images have been moved to Amazon's S3 service.  The thumbnails don't exist at their old location.  This breaks scripts that displayed the thumbnails, like my took that creates the list of past labs here on the wiki.  But moving them to Amazon seems good, so I'm just going to update that script.
    Update: To my pleasant surprise, the thumbnails are back at the old URL on the Eterna servers, as well as thei new location in the Amazon cloud.  Not only that, but thumbnails for the newest labs have been added, too.  So I don't have to update the script right away.  For me, this is striking evidence that Eterna really is serious about supporting player-led developments.  A big thanks to the Eterna devs in general and (presumably) to Justin in particular.
  2. The format of the type=past-labs query (e.g. https://eternagame.org/get/?type=past_labs&skip=0&size=21 response has changed.  It may well be completely backward compatible; I'm not sure because I don't have a complete record of what it was.  But as it stands now, a solution has a field named "puzzles", which is an array of objects.  Each element of the array is an object which has a field also called "puzzles", which is also an array.  Each element of this array is a nid which seems to correspond to a secondary structure, because the query "https://s3.amazonaws.com/eterna/puzzle_mid_thumbnails/thumbnail<nid>.png" returns a thumbnail image of the target structure for that lab. I think this new level of indirection is there to support labs that allow sequences with differernt lengths and target structures. The reproducibility lab is one example, but I remember Rhiju talking about supporting this, long before the reproducibility lab came into being.

Omei (talk) 01:30, 28 September 2013 (UTC)

---

type=lab: Doesn't return anything meaningful for labs in last synthesis round

Apparently Justin restored the behavior of the lab query for existing labs, but didn't cary that over to new labs.  A query for a new lab returns

{"data":{"lab":null,"comments":[],"supercomments":[],"num_synthesized":0,"follow":[],"num_slots":false,"sum_picks":null,"num_solutions":"0","my_votes":null,"uid":"57675"},"memcache":true}

So any existing scripts that use the lab query are still broken for new labs. I'll raise this issue with Justin.

Resolution: Justin pointed out that I was incorrect; the lab query for the latest round returns the same results it used to. The cause of my confusion is that the in-game URLs can be misleading. If you go to the past labs page and choose the Reprodicibility Lab, you'r be taken to the URL https://eternagame.org/web/lab/3376330/. But 3376330 is not the lab ID; it is the project (a new construct)  ID.  To determine the lab ID, you have to click through to the browse page, whose URL is https://eternagame.org/web/browse/3293294/. Here we see the lab ID, and if you use that in a type=lab GET query, you'll get the results you expect.

Hopefully the project/lab terminolgy will get straigthened out.

Omei (talk) 23:45, 30 September 2013 (UTC)

----

Missing Semicirle - 2 bends and Semicircle - 5 bends in past labs.

This is a strange one. I don't know that it is related to the recent server changes, but I'll note it here.

The two labs Semicircle - 2 bends and Semicircle - 5 bends, which were part of Cloud Lab 8, have disappeared from the past_labs query and replaced by Semicircle - 3 bends and Semicircle - 4 bends, which were part of Cloud Lab 9. The easiest way to confirm this is to look at the most recent diff for the list of labs.  Search for "2 bends". I verified that the GET query for past_labs isn't returning them, but the queries for solutions and lab still do.

Omei (talk) 01:57, 3 October 2013 (UTC)

 

These two labs are under Proposed labs for now, as the new button for open 2 round was so easy to hit that several lab makers hit it by accident. Justin has disabled the option for now.

-- Eli Fisker (talk) 20:46, 16 October 2013 (UTC)

----