CINXE.COM
DOE PAGES API (v1) Documentation
<!doctype html> <html lang="en"> <head> <meta charset='utf-8'> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <meta name="viewport" content="width=device-width"> <title>DOE PAGES API (v1) Documentation</title> <link rel="icon" type="image/png" href="https://www.osti.gov/sites/www.osti.gov/files/public/styles/large/public/image-files/OSTI_favicon_32px.png" /> <script src="/pages/js/jquery.min.js"></script> <script src='/pages/js/api-docs/flatdoc.js'></script> <script src='/pages/js/api-docs/scroll.js'></script> <link href="/pages/css/bootstrap.css" rel="stylesheet"> <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700,800|Roboto+Slab:400,300,700" rel="stylesheet" type="text/css"> <link href="/pages/css/bootstrap-theme.css" rel="stylesheet"> <link href="/pages/css/api-docs/api-docs.css" rel="stylesheet"> <!-- Meta --> <meta content="DOE PAGES API (v1) Documentation" property="og:title"> <meta content="REST API for accessing the DOE PAGES repository of research resulting from DOE R&D funding" name="description"> <script type="text/javascript"> function openTab(tabId, tabSetId) { const tabLinks = document.getElementById(tabSetId).querySelectorAll('.nav-link'); const tabContents = document.getElementById(tabSetId).nextElementSibling.querySelectorAll('.tab-pane'); tabLinks.forEach(function(link) { link.classList.remove('active'); }); tabContents.forEach(function(content) { content.classList.remove('show' , 'active'); }); const clickedTab = document.getElementById(tabId + '-tab'); clickedTab.classList.add('active'); const targetTab = document.getElementById(tabId); targetTab.classList.add('show' , 'active'); } </script> </head> <body role='flatdoc'> <div class="top-band row"> <div class="col-xs-12"> <img src="/pages/img/PAGES_R_white220px-min.png" alt="DOE PAGES" style="margin-top:-10px;margin-bottom:0px;margin-left:15px;" height="60"> <h1 style="display:inline-block;color: #fff; margin:24px; margin-left:30px; font-weight: 300;">API Documentation</h1> </div> </div> <div class="row"> <div class="col-xs-2 toc-wrapper"> <div id="toc" class="toc affix" role="flatdoc-menu-bak"> <ul> <li id="root-item" class="level-0"> <ul class="level-1" id="root-list"> <li id="introduction-item" class="level-1"> <a id="introduction-link" href="#introduction" class="level-1">Introduction</a></li> <li id="general-guidelines-item" class="level-1"><a id="general-guidelines-link" href="#general-guidelines" class="level-1">General Guidelines</a> <ul class="level-2" id="general-guidelines-list"> <li id="general-guidelines-httpmethods-item" class="level-2"> <a id="general-guidelines-httpmethods-link" href="#general-guidelines-httpmethods" class="level-2">HTTP Methods</a> </li> <li id="general-guidelines-responseformats-item" class="level-2"> <a id="general-guidelines-responseformats-link" href="#general-guidelines-responseformats" class="level-2">Response Formats</a> </li> <li id="general-guidelines-responseheaders-item" class="level-2"> <a id="general-guidelines-responseheaders-link" href="#general-guidelines-responseheaders" class="level-2">Response Headers</a> </li> <li id="general-guidelines-pagination-item" class="level-2"> <a id="general-guidelines-pagination-link" href="#general-guidelines-pagination" class="level-2">Pagination Structure</a> </li> </ul> </li> <li id="record-model-item" class="level-1"><a id="record-model-link" href="#record-model" class="level-1">Record Model</a> <ul class="level-2" id="record-model-list"> <li id="record-model-httpstatuscodes-item" class="level-2"> <a id="record-model-httpstatuscodes-link" href="#record-model-httpstatuscodes" class="level-2">HTTP Status Codes</a> </li> <li id="record-model-fields-item" class="level-2"><a id="record-model-fields-link" href="#record-model-fields" class="level-2">Record Fields</a></li> </ul> </li> <li id="error-model-item" class="level-1"><a id="error-model-link" href="#error-model" class="level-1">Error Model</a> <ul class="level-2" id="error-model-list"> <li id="error-model-httpstatuscodes-item" class="level-2"> <a id="error-model-httpstatuscodes-link" href="#error-model-httpstatuscodes" class="level-2">HTTP Status Codes</a> </li> <li id="error-model-fields-item" class="level-2"><a id="error-model-fields-link" href="#error-model-fields" class="level-2">Error Fields</a></li> </ul> </li> <li id="endpoints-item" class="level-1"><a id="endpoints-link" href="#endpoints" class="level-1">Endpoints</a> <ul class="level-2" id="records-collection-list"> <li id="endpoints-recordlist-item" class="level-2"> <a id="endpoints-recordlist-link" href="#endpoints-recordlist" class="level-2">Record List (Search)</a> </li> <li id="endpoints-singlerecord-item" class="level-2"> <a id="endpoints-singlerecord-link" href="#endpoints-singlerecord" class="level-2">Single Record by ID</a> </li> </ul> </li> </ul> </li> </ul> </div> </div> <div class="col-xs-10 page-wrapper"> <div class="row"> <div class="col-xs-12"> <div id="spacer-top"></div> <!-- introduction --> <div class="anchor" id="introduction"></div> <section> <div class="row"> <div class="col-xs-12 section-title"> <h2>Introduction</h2> </div> </div> <div class="row"> <div class="col-xs-6 content-box" role="flatdoc-content-bak"> <p>The DOE PAGES<sup>®</sup> API allows you to query the Department of Energy Office of Scientific and Technical Information's (OSTI) repository containing scholarly scientific publications resulting from DOE research funding.</p> <p>The API is built on a REST architecture, providing predictable URLs that make writing applications easy. The API is HTTP-based, so it can be accessed using a wide variety of clients; most examples are illustrated using the cURL command to demonstrate basic use cases.</p> <p>The list of resources available through the API, and their corresponding reference documentation, will always be made available at the API root endpoint (this document).</p> </div> <div class="col-xs-6 example-box"> <h3>API Root Endpoint</h3> <pre><code class="lang-javascript">https://www.osti.gov/pages/api/v1</span></code></pre> </div> </div> </section> <div class="anchor" id="general-guidelines"></div> <section> <div class="row"> <div class="col-xs-12 section-title"> <h2>General Guidelines</h2> </div> </div> <div class="row"> <div class="col-xs-6 content-box" role="flatdoc-content-bak"> <p>Each resource endpoint in the API will vary slightly in some respects, such as what query parameters are valid for that type of request and how the expected output may be structured. These variations will be outlined in detail in the resource-specific sections below. There are, however, some general rules and expectations that are common to all interactions with the API.</p> </div> <div class="col-xs-6 example-box"> </div> </div> </section> <div class="anchor sub" id="general-guidelines-httpmethods"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>HTTP Methods</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>The DOE PAGES API uses the HTTP verb (method) associated with the incoming request to identify the type of action being performed. Note that at this time the DOE PAGES API has methods for querying data only, and therefore all requests to the API will be GET requests.</p> <table class="table"> <thead> <tr> <th id="req-method-table" colspan="2" class="table-title">Request Methods</th> </tr> <tr> <th id="req-method" class="col-title">Method</th> <th id="req-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="req-method req-method-table">GET</td> <td headers="req-description req-method-table">Used for retrieving resources.</td> </tr> <tr> <td headers="req-method req-method-table" class="text-muted">POST</td> <td headers="req-description req-method-table" class="text-muted">Used for creating resources and performing resourceactions.<br /> <em class="text-warning">Not currently valid for DOE PAGES API resource requests</em></td> </tr> <tr> <td headers="req-method req-method-table" class="text-muted">PUT</td> <td headers="req-description req-method-table" class="text-muted">Used for updating resources.<br /> <em class="text-warning">Not currently valid for DOE PAGES API resource requests</em></td> </tr> <tr> <td headers="req-method req-method-table" class="text-muted">DELETE</td> <td headers="req-description req-method-table" class="text-muted">Used for deleting resources.<br /> <em class="text-warning">Not currently valid for DOE PAGES API resource requests</em></td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <p>Using the GET method, you can retrieve a list (collection) of resources or details of a particular resource.</p> <p>To get a list of records:</p> <pre><code>$ curl https://www.osti.gov/pages/api/v1/records</code></pre> <p>To get details of a record with a particular ID:</p> <pre><code>$ curl https://www.osti.gov/pages/api/v1/records/{osti_id}</code></pre> </div> </div> </section> <div class="anchor sub" id="general-guidelines-responseformats"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Response Formats</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p> By default, results from the DOE PAGES API will be returned in JSON format. By specifying an expected mime type in the <code class="text-muted">Accept</code> header of the request, results can also be returned in any of JSON, XML, or BibTeX formats. </p> <table class="table"> <thead> <tr> <th id="format-types-accept-headers" colspan="2" class="table-title">Format Types and Accept Headers</th> </tr> <tr> <th id="format" class="col-title">Format</th> <th id="accept-header" class="col-title">Accept header</th> </tr> </thead> <tbody> <tr> <td headers="format format-types-accept-headers">JSON</td> <td headers="accept-header format-types-accept-headers">application/json</td> </tr> <tr> <td headers="format format-types-accept-headers">XML</td> <td headers="accept-header format-types-accept-headers">application/xml</td> </tr> <tr> <td headers="format format-types-accept-headers">BibTeX</td> <td headers="accept-header format-types-accept-headers">application/x-bibtex</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <p>Specifying the <code>Accept</code> header in the request, you can retrieve results in a particular format.</p> <ul class="nav nav-tabs" id="myTabs1"> <li class="nav-item"> <button class="nav-link active" id="tab1-tab" onclick="openTab('tab1' , 'myTabs1')">JSON</button> </li> <li class="nav-item"> <button class="nav-link" id="tab2-tab" onclick="openTab('tab2' , 'myTabs1')">XML</button> </li> <li class="nav-item"> <button class="nav-link" id="tab3-tab" onclick="openTab('tab3' , 'myTabs1')">BibTeX</button> </li> </ul> <div class="tab-content" id="myTabContent1"> <div class="tab-pane show active" id="tab1" role="tabpanel" ario-labelledby="tab1-tab"> <p>To get a record's metadata in JSON format:</p> <pre><code>$ curl https://www.osti.gov/pages/api/v1/records/{osti_id} \ -H 'Accept: application/json'</code></pre> </div> <div class="tab-pane" id="tab2" role="tabpanel" ario-labelledby="tab2-tab"> <p>To get a record's metadata in XML format:</p> <pre><code>$ curl https://www.osti.gov/pages/api/v1/records/{osti_id} \ -H 'Accept: application/xml'</code></pre> </div> <div class="tab-pane" id="tab3" role="tabpanel" ario-labelledby="tab3-tab"> <p>To get a record's metadata in BibTeX format:</p> <pre><code>$ curl https://www.osti.gov/pages/api/v1/records/{osti_id} \ -H 'Accept: application/x-bibtex'</code></pre> </div> </div> </div> </div> </section> <div class="anchor sub" id="general-guidelines-responseheaders"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Response Headers</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>Responses from the API will include certain common HTTP headers, providing details about the response or the included content.</p> <table class="table"> <thead> <tr> <th id="common-response-headers" colspan="2" class="table-title">Common Response Headers</th> </tr> <tr> <th id="response-header" class="col-title">Response Header</th> <th id="response-header-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="response-header common-response-headers">Date</td> <td headers="response-header-description common-response-headers">The date the response is issued, in RFC 1123 format</td> </tr> <tr> <td headers="response-header common-response-headers">Content-Type</td> <td headers="response-header-description common-response-headers">The mime type in which the response data is formatted</td> </tr> <tr> <td headers="response-header common-response-headers">X-Total-Count</td> <td headers="response-header-description common-response-headers">For responses containing data, the number of records returned in the current response</td> </tr> <tr> <td headers="response-header common-response-headers">Link</td> <td headers="response-header-description common-response-headers">If more matching records are available than are returned in the current response, this will contain links to more pages in RFC 5988 format</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <h3>Example Response Headers</h3> <pre><code>HTTP/1.1 200 OK Date: Thu, 26 May 2016 16:25:04 GMT Content-Type: application/json X-Total-Count: 50 Link: <https://www.osti.gov/pages/api/v1/records?page=2>; rel="next", <https://www.osti.gov/pages/api/v1/records?page=3>; rel="last" Content-Length: 3911</code></pre> </div> </div> </section> <div class="anchor sub" id="general-guidelines-pagination"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Pagination</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>Requests that return multiple records will be paginated to 20 records by default; the number of records per page can be modified by specifying a numerical value for the <code class="text-muted">?rows</code> parameter, and the specific page with the <code class="text-muted">?page</code> parameter (default 1). If more matching records exist, the <code class="text-muted">Link</code> response header will contain links to additional pages of data, in RFC 5988 format. The specific type of link is denoted by the "rel" value.</p> <table class="table"> <thead> <tr> <th id="link-header-vals" colspan="2" class="table-title">Link Header Rel Values</th> </tr> <tr> <th id="link-header-name" class="col-title">Name</th> <th id="link-header-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="link-header-name link-header-vals">next</td> <td headers="link-header-description link-header-vals">The link relation for the immediate next page of results</td> </tr> <tr> <td headers="link-header-name link-header-vals">last</td> <td headers="link-header-description link-header-vals">The link relation for the last page of results</td> </tr> <tr> <td headers="link-header-name link-header-vals">first</td> <td headers="link-header-description link-header-vals">The link relation for the last page of results</td> </tr> <tr> <td headers="link-header-name link-header-vals">prev</td> <td headers="link-header-description link-header-vals">The link relation for the immediate previous page of results</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <h3>Example Link Header Values</h3> <pre><code> $ curl https://www.osti.gov/pages/api/v1/records?page=2&rows=20 HTTP/1.1 200 OK ... X-Total-Count: 250 Link: <https://www.osti.gov/pages/api/v1/records?page=3&rows=20>; rel="next", <https://www.osti.gov/pages/api/v1/records?page=13&rows=20>; rel="last", <https://www.osti.gov/pages/api/v1/records?page=1&rows=20>; rel="first", <https://www.osti.gov/pages/api/v1/records?page=1&rows=20>; rel="prev" ...</code></pre> </div> </div> </section> <div class="anchor" id="record-model"></div> <section> <div class="row"> <div class="col-xs-12 section-title"> <h2>Record Model</h2> </div> </div> <div class="row"> <div class="col-xs-6 content-box" role="flatdoc-content-bak"> <p>Responses returning data all return the same basic structure, formatted as appropriate for the content type requested.</p> </div> <div class="col-xs-6 example-box"> </div> </div> </section> <div class="anchor sub" id="record-model-httpstatuscodes"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>HTTP Status Codes</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>A successful response from the API will always return an HTTP status code of 200.</p> <table class="table"> <thead> <tr> <th id="http-success-table" colspan="2" class="table-title">HTTP Success Status</th> </tr> <tr> <th id="http-success-status-title" class="col-title">Status</th> <th id="http-success-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="http-success-status-title http-success-table">200</td> <td headers="http-success-description http-success-table">OK</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> </div> </div> </section> <div class="anchor sub" id="record-model-fields"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Record Fields</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>Results are always presented as a list of Record objects, formatted according to the content type requested. For JSON, records are returned as an array of objects. For XML, records are returned as <code class="text-muted"><record></code> elements wrapped in a <code class="text-muted"><records></code> container. BibTeX results are formatted serially.</p> <table class="table"> <thead> <tr> <th id="record-fields" colspan="2" class="table-title">Record Fields</th> </tr> <tr> <th id="record-field-name" class="col-title">Field Name</th> <th id="record-field-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="record-field-name record-fields">osti_id</td> <td headers="record-field-description record-fields">The unique OSTI identifier for the record</td> </tr> <tr> <td headers="record-field-name record-fields">title</td> <td headers="record-field-description record-fields">A name or title by which the record is known</td> </tr> <tr> <td headers="record-field-name record-fields">authors</td> <td headers="record-field-description record-fields">The person(s) primarily responsible for the creation of the data</td> </tr> <tr> <td headers="record-field-name record-fields">subjects</td> <td headers="record-field-description record-fields">A list of subjects, keywords, or key phrases describing the resource </td> </tr> <tr> <td headers="record-field-name record-fields">description</td> <td headers="record-field-description record-fields">A short description or abstract</td> </tr> <tr> <td headers="record-field-name record-fields">publisher</td> <td headers="record-field-description record-fields">The name of the entity that holds, archives, distributes, releases, or produces the resource</td> </tr> <tr> <td headers="record-field-name record-fields">country_publication</td> <td headers="record-field-description record-fields">The country in which this version of the record was published</td> </tr> <tr> <td headers="record-field-name record-fields">publication_date</td> <td headers="record-field-description record-fields">The publication date, in ISO-8601 format</td> </tr> <tr> <td headers="record-field-name record-fields">entry_date</td> <td headers="record-field-description record-fields">The date the record was added or last modified, in ISO-8601 format</td> </tr> <tr> <td headers="record-field-name record-fields">doi</td> <td headers="record-field-description record-fields">The Digital Object Identifier (DOI)</td> </tr> <tr> <td headers="record-field-name record-fields">journal_name</td> <td headers="record-field-description record-fields">The name of the journal the article was published in</td> </tr> <tr> <td headers="record-field-name record-fields">journal_volume</td> <td headers="record-field-description record-fields">The journal volume containing this article</td> </tr> <tr> <td headers="record-field-name record-fields">journal_issue</td> <td headers="record-field-description record-fields">The journal issue containing to this article</td> </tr> <tr> <td headers="record-field-name record-fields">product_type</td> <td headers="record-field-description record-fields">The product type of the record (defaults to "Journal Article")</td> </tr> <tr> <td headers="record-field-name record-fields">dataset_content_type</td> <td headers="record-field-description record-fields">A descriptor that best describes the resource content (simulation, numeric, etc.)</td> </tr> <tr> <td headers="record-field-name record-fields">language</td> <td headers="record-field-description record-fields">The primary language of the resource</td> </tr> <tr> <td headers="record-field-name record-fields">availability</td> <td headers="record-field-description record-fields">If applicable, the office or organization to refer access requests to </td> </tr> <tr> <td headers="record-field-name record-fields">research_org</td> <td headers="record-field-description record-fields">If credited, the organization name primarily responsible for conducting the research</td> </tr> <tr> <td headers="record-field-name record-fields">sponsor_org</td> <td headers="record-field-description record-fields">If credited, the organization name that sponsored / funded the research </td> </tr> <tr> <td headers="record-field-name record-fields">contributor_org</td> <td headers="record-field-description record-fields">If credited, the organization(s) contributing to the research</td> </tr> <tr> <td headers="record-field-name record-fields">format</td> <td headers="record-field-description record-fields">Additional format / paging information</td> </tr> <tr> <td headers="record-field-name record-fields">report_number</td> <td headers="record-field-description record-fields">The report number associated with the entry</td> </tr> <tr> <td headers="record-field-name record-fields">doe_contract_number</td> <td headers="record-field-description record-fields">The DOE contract number associated with the entry</td> </tr> <tr> <td headers="record-field-name record-fields">links</td> <td headers="record-field-description record-fields">A multivalued field containing link references for this article, typed by "rel" attribute (HATEOAS constraint)</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <h3>Example Response</h3> <ul class="nav nav-tabs" id="myTabs2"> <li class="nav-item"> <button class="nav-link active" id="tab4-tab" onclick="openTab('tab4', 'myTabs2')">JSON</button> </li> <li> <button class="nav-link" id="tab5-tab" onclick="openTab('tab5', 'myTabs2')">XML</button> </li> <li> <button class="nav-link" id="tab6-tab" onclick="openTab('tab6', 'myTabs2')">BibTeX</button> </li> </ul> <div class="tab-content" id="myTabContent2"> <div class="tab-pane show active" id="tab4" role="tabpanel" aria-labelledby="tab4-tab"> <pre><code>HTTP/1.1 200 OK Content-Type: application/json</code></pre> <pre><code>[ { "osti_id": "{osti_id}", "title": "Example Title", "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", "authors": [ "Nominator, Lois D.", "Dactyl, Terry", "Anthemum, Chris" "Turner, Paige" ], "doi": "https://doi.org/10.5555/12345678", "journal_name": "The Journal of Psychoceramics", "journal_volume": "60", "journal_issue": "5", "publisher": "Example Publisher", "country_publication": "United States", "product_type": "Journal Article", "article_type": "Accepted Manuscript", "language": "English", "publication_date": "2015-06-02T04:00:00Z", "entry_date": "2016-09-07T04:00:00Z", "sponsor_orgs": [ "USDOE", "Example Sponsor Organization 2" ], "research_orgs": [ "Example Research Organization 1", "Example Research Organization 2" ], "report_number": "XX-YY-15-12345; XYZ-2015-4321A", "doe_contract_number": "ACXX-012345678; ACXX-987654321", "availability": "", "format": "Medium: ED; Size: p. 445-455", "subjects": [ "magnetic relaxometry", "nanoparticles", "cancer", "relaxometry" ], "links": [{ "rel": "citation", "href": "https://www.osti.gov/biblio/{osti_id}" }, { "rel": "fulltext", "href": "https://www.osti.gov/servlets/purl/{osti_id}" }] } ]</code></pre> </div> <div class="tab-pane" id="tab5" role="tabpanel" aria-labelledby="tab5-tab"> <pre><code>HTTP/1.1 200 OK Content-Type: application/xml</code></pre> <pre><code><?xml version="1.0"?> <records> <record> <osti_id>{osti_id}</osti_id> <title>Example Title</title> <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</description> <authors> <author>Nominator, Lois D.</author> <author>Dactyl, Terry</author> <author>Anthemum, Chris</author> <author>Turner, Paige</author> </authors> <doi>https://doi.org/10.5555/12345678</doi> <journal_name>The Journal of Psychoceramics</journal_name> <journal_volume>60</journal_volume> <journal_issue>5</journal_issue> <publisher>Example Publisher</publisher> <country_publication>United States</country_publication> <product_type>Journal Article</product_type> <article_type>Accepted Manuscript</article_type> <language>English</language> <publication_date>2015-06-02T04:00:00Z</publication_date> <entry_date>2016-09-07T04:00:00Z</entry_date> <sponsor_orgs> <sponsor_org>USDOE</sponsor_org> <sponsor_org>Example Sponsor Organization 2</sponsor_org> </sponsor_orgs> <research_orgs> <research_org>Example Research Organization 1</research_org> <research_org>Example Research Organization 2</research_org> </research_org> <report_number>XX-YY-15-12345; XYZ-2015-4321A</report_number> <doe_contract_number>ACXX-012345678; ACXX-987654321</doe_contract_number> <availability></availability> <format>Medium: ED; Size: p. 445-455</format> <subjects> <subject>magnetic relaxometry</subject> <subject>nanoparticles</subject> <subject>cancer</subject> <subject>relaxometry</subject> </subjects> <links> <link rel="citation" href="https://www.osti.gov/pages/biblio/{osti_id}" /> <link rel="fulltext" href="https://www.osti.gov/servlets/purl/{osti_id}" /> </links> </record> </records></code></pre> </div> <div class="tab-pane" id="tab6" role="tabpanel" aria-labelledby="tab6-tab"> <pre><code>HTTP/1.1 200 OK Content-Type: application/x-bibtex</code></pre> <pre><code>@misc{osti_{osti_id}, title = {Example Title}, author = {Nominator, L. and Dactyl, T. and Anthemum, C. and Turner, P.}, abstractNote = {Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}, doi = {https://doi.org/10.5555/12345678}, place = {United States}, year = 2015, month = 9, note = {An optional note}, }</code></pre> </div> </div> </div> </div> </section> <div class="anchor" id="error-model"></div> <section> <div class="row"> <div class="col-xs-12 section-title"> <h2>Error Model</h2> </div> </div> <div class="row"> <div class="col-xs-6 content-box" role="flatdoc-content-bak"> <p>If for some reason the API returns an error response, it will be formatted as appropriate for the content type requested. All error responses have the same basic structure.</p> </div> <div class="col-xs-6 example-box"> </div> </div> </section> <div class="anchor sub" id="error-model-httpstatuscodes"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>HTTP Status Codes</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>Errors will be returned with an HTTP error status code appropriate to the type of error encountered.</p> <table class="table"> <thead> <tr> <th id="http-error-table" colspan="2" class="table-title">HTTP Error Status</th> </tr> <tr> <th id="http-error-status" class="col-title">Status</th> <th id="http-error-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="http-error-status http-error-table">400</td> <td headers="http-error-description http-error-table">Bad request</td> </tr> <tr> <td headers="http-error-status http-error-table">401</td> <td headers="http-error-description http-error-table">Unauthorized</td> </tr> <tr> <td headers="http-error-status http-error-table">404</td> <td headers="http-error-description http-error-table">Resource Not Found</td> </tr> <tr> <td headers="http-error-status http-error-table">405</td> <td headers="http-error-description http-error-table">Method Not Allowed</td> </tr> <tr> <td headers="http-error-status http-error-table">500</td> <td headers="http-error-description http-error-table">Internal Error</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> </div> </div> </section> <div class="anchor sub" id="error-model-fields"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Error Fields</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p>Errors are always presented as a single object, formatted according to the content type requested.</p> <table class="table"> <thead> <tr> <th id="error-field-table" colspan="2" class="table-title">Error Fields</th> </tr> <tr> <th id="error-field-name" class="col-title">Field Name</th> <th id="error-field-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="error-field-name error-field-table">statusCode</td> <td headers="error-field-description error-field-table">The response error code, duplicated for convenience</td> </tr> <tr> <td headers="error-field-name error-field-table">statusMessage</td> <td headers="error-field-description error-field-table">A brief description of the error type</td> </tr> <tr> <td headers="error-field-name error-field-table">errorDescription</td> <td headers="error-field-description error-field-table">A more detailed description of the specific error cause</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <h3>Example Error</h3> <ul class="nav nav-tabs" id="myTabs3"> <li class="nav-item"> <button class="nav-link active" id="tab7-tab" onclick="openTab('tab7', 'myTabs3')">JSON</a> </li> <li> <button class="nav-link" id="tab8-tab" onclick="openTab('tab8', 'myTabs3')">XML</a> </li> <li> <button class="nav-link" id="tab9-tab" onclick="openTab('tab9', 'myTabs3')">BibTeX</a> </li> </ul> <div class="tab-content" id="myTabContent3"> <div class="tab-pane show active" id="tab7" role="tabpanel" aria-labelledby="tab7-tab"> <pre><code>HTTP/1.1 404 Not Found Content-Type: application/json</code></pre> <pre><code>{ "statusCode": 404, "statusMessage": "Not Found", "errorDescription": "No record matching the supplied OSTI ID was found" }</code></pre> </div> <div class="tab-pane" id="tab8" role="tabpanel" aria-labelledby="tab8-tab"> <pre><code>HTTP/1.1 404 Not Found Content-Type: application/xml</code></pre> <pre><code><?xml version="1.0"?> <error> <statusCode>404</statusCode> <statusMessage>Not Found</statusMessage> <errorDescription>No record matching the supplied OSTI ID was found</errorDescription> </error></code></pre> </div> <div class="tab-pane" id="tab9" role="tabpanel" aria-labelledby="tab9-tab"> <pre><code>HTTP/1.1 404 Not Found Content-Type: application/x-bibtex</code></pre> <pre><code>404 Not Found No record matching the supplied OSTI ID was found</code></pre> </div> </div> </div> </div> </section> <div class="anchor" id="endpoints"></div> <section> <div class="row"> <div class="col-xs-12 section-title"> <h2>Endpoints</h2> </div> </div> <div class="row"> <div class="col-xs-6 content-box" role="flatdoc-content-bak"> <p>The DOE PAGES API currently supports two endpoints, both of which are data retrieval endpoints and as such only GET method requests are valid. All endpoints are relative to the root endpoint.</p> </div> <div class="col-xs-6 example-box"> <h3>API Root Endpoint</h3> <pre><code class="lang-javascript">https://www.osti.gov/pages/api/v1</span></code></pre> </div> </div> </section> <div class="anchor sub" id="endpoints-recordlist"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Record List (Search)</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p><code class="text-muted">GET</code> /records</p> <p>The record list endpoint allows you to search for lists of records in DOE PAGES by a variety of criteria.</p> <table class="table"> <thead> <tr> <th id="record-query-params" colspan="2" class="table-title">Record List Query Parameters</th> </tr> <tr> <th id="record-query-param" class="col-title">Parameter</th> <th id="record-query-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="record-query-param record-query-params">q</td> <td headers="record-query-description record-query-params">General query field, will search full record for provided terms</td> </tr> <tr> <td headers="record-query-param record-query-params">osti_id</td> <td headers="record-query-description record-query-params">The unique OSTI identifier for a record</td> </tr> <tr> <td headers="record-query-param record-query-params">fulltext</td> <td headers="record-query-description record-query-params">Searches the article full text (if available) for the provided terms </td> </tr> <tr> <td headers="record-query-param record-query-params">biblio</td> <td headers="record-query-description record-query-params">Searches the bibliographic information for the provided terms</td> </tr> <tr> <td headers="record-query-param record-query-params">author</td> <td headers="record-query-description record-query-params">Searches the author entries</td> </tr> <tr> <td headers="record-query-param record-query-params">title</td> <td headers="record-query-description record-query-params">Searches within document titles</td> </tr> <tr> <td headers="record-query-param record-query-params">identifier</td> <td headers="record-query-description record-query-params">Finds records based on common identifiers (report number, contract number, etc.)</td> </tr> <tr> <td headers="record-query-param record-query-params">sponsor_org</td> <td headers="record-query-description record-query-params">Searches the sponsoring organization field</td> </tr> <tr> <td headers="record-query-param record-query-params">research_org</td> <td headers="record-query-description record-query-params">Searches the research organization field</td> </tr> <tr> <td headers="record-query-param record-query-params">contributing_org</td> <td headers="record-query-description record-query-params">Searches the contributing organization field</td> </tr> <tr> <td headers="record-query-param record-query-params">source_id</td> <td headers="record-query-description record-query-params">A code specifying the organization that submitted the record</td> </tr> <tr> <td headers="record-query-param record-query-params">dataset_content_type</td> <td headers="record-query-description record-query-params">Specifies the category of dataset / collection</td> </tr> <tr> <td headers="record-query-param record-query-params">publication_date_start</td> <td headers="record-query-description record-query-params">Beginning publication date boundary in MM/DD/YYYY format</td> </tr> <tr> <td headers="record-query-param record-query-params">publication_date_end</td> <td headers="record-query-description record-query-params">End publication date boundary in MM/DD/YYYY format</td> </tr> <tr> <td headers="record-query-param record-query-params">entry_date_start</td> <td headers="record-query-description record-query-params">Beginning entry date boundary in MM/DD/YYYY format</td> </tr> <tr> <td headers="record-query-param record-query-params">entry_date_end</td> <td headers="record-query-description record-query-params">Ending entry date boundary in MM/DD/YYYY format</td> </tr> <tr> <td headers="record-query-param record-query-params">language</td> <td headers="record-query-description record-query-params">Finds records by language</td> </tr> <tr> <td headers="record-query-param record-query-params">country</td> <td headers="record-query-description record-query-params">Finds records by country of publication</td> </tr> <tr> <td headers="record-query-param record-query-params">site_ownership_code</td> <td headers="record-query-description record-query-params">Finds records by the ID code of the submitting organization</td> </tr> <tr> <td headers="record-query-param record-query-params">sort</td> <td headers="record-query-description record-query-params">Specifies a field name on which to sort</td> </tr> <tr> <td headers="record-query-param record-query-params">order</td> <td headers="record-query-description record-query-params">Specifies the sort order (one of asc or desc)</td> </tr> <tr> <td headers="record-query-param record-query-params">rows</td> <td headers="record-query-description record-query-params">The number of rows per page to return (default 20)</td> </tr> <tr> <td headers="record-query-param record-query-params">page</td> <td headers="record-query-description record-query-params">The specific page of records to return (default 1)</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <h3>Record List Endpoint</h3> <pre><code class="lang-javascript">https://www.osti.gov/pages/api/v1/records</span></code></pre> </div> </div> </section> <div class="anchor sub" id="endpoints-singlerecord"></div> <section class="sub"> <div class="row"> <div class="col-xs-12 section-title"> <h3>Single Record by ID</h3> </div> </div> <div class="row"> <div class="col-xs-6 content-box"> <p><code class="text-muted">GET</code> /records/{osti_id}</p> <p>The single record by id endpoint allows you to retrieve details for a specific record by providing the appropriate OSTI ID value as the key in the request path.</p> <table class="table"> <thead> <tr> <th id="single-record-query-params" colspan="2" class="table-title">Record List Query Parameters</th> </tr> <tr> <th id="single-record-query-param" class="col-title">Parameter</th> <th id="single-record-query-description" class="col-title">Description</th> </tr> </thead> <tbody> <tr> <td headers="single-record-query-param single-record-query-params" class="text-center text-muted">none</td> </tr> </tbody> </table> </div> <div class="col-xs-6 example-box"> <h3>Single Record Endpoint</h3> <pre><code class="lang-javascript">https://www.osti.gov/pages/api/v1/records/{osti_id}</span></code></pre> </div> </div> </section> <div class="anchor sub" id="footer-text"></div> <section class="sub"> <div class="row"> <div class="col-xs-6 content-box"> <div style="margin-top: 400px; padding-top: 30px; border-top: 1px solid #ddd;"> <p class="text-muted">The DOE PAGES API is actively in development; the documentation should be kept up to date with the functionality of the current release. If you have any questions or suggestions, please <a href="mailto:comments@osti.gov">let us know</a>.</p> <div class="clearfix"></div> </div> </div> <div class="col-xs-6 example-box"> </div> </div> </section> </div> </div> </div> </div> </body> </html>