ELINK 241.6 API Documentation

Introduction

The ELINK 241.6 API provides a REST service to both access existing ELINK metadata as well as a means to submit new records and update existing ones.

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.

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).

API Root Endpoint

https://www.osti.gov/elink/2416api

General Guidelines

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.

Authentication

The ELINK 241.6 API requires basic authentication in order to both access and post records or updates to the service. An existing ELINK access account allows access to your site's set of records, provided the account has the appropriate privileges to access the information. Please contact ELINK support for additional information or you may register for an ELINK account here.

API authentication may be passed through the use of the basic HTTP "Authentication" header, or via the -u switch if using the command-line cURL tool.

Using the command-line curl client:

$ curl -u 'username:password' https://www.osti.gov/elink/2416api?osti_id={osti id}

Using the Apache HTTPClient code for a GET request in Java:


    CloseableHttpClient client = HttpClient.create().build();
    HttpGet get = new HttpGet("https://www.osti.gov/elink/2416api?osti_id=" + my_osti_id);
    String authentication = my_username + ":" + my_password;
    byte[] encoded = Base64.encodeBase64(authentication.getBytes(Charset.forName("ISO-8859-1")));
    get.addHeader(HttpHeaders.AUTHORIZATION, "Basic " + new String(encoded));
    
    try {
        HttpResponse response = client.execute(get);

        // ...read response
    } finally {
        client.close();
    }

HTTP Methods

The ELINK 241.6 API uses the HTTP verb (method) associated with the incoming request to identify the type of action being performed. GET requests obtain information on existing metadata records, while POST is used to submit both new records and updates to existing records in ELINK.

Request Methods
Method Description
GET Used for retrieving existing metadata records.
POST Used for creating new metadata and updating existing records.
PUT Typically used for updating resources.
Not currently used by ELINK API requests
DELETE Typically used for deleting resources.
Not currently valid for ELINK API requests

Using the GET method, you can retrieve a list (collection) of resources or details of a particular resource.

To get a list of datasets:

$ curl -u 'username:password' https://www.osti.gov/elink/2416api?page=0

To get details of a dataset with a particular OSTI ID:

$ curl -u 'username:password' https://www.osti.gov/elink/2416api?osti_id={osti id}

Response Headers

Responses from the API will include certain common HTTP headers, providing details about the response or the included content.

Common Response Headers
Response Header Description
Date The date the response is issued, in RFC 1123 format
Content-Type The mime type in which the response data is formatted
X-Total-Count For responses containing data, the number of records returned in the current response
Link If more matching records are available than are returned in the current response, this will contain links to more pages in RFC 5988 format

Example Response Headers



HTTP/1.1 200 OK

Date: Thu, 26 May 2016 16:25:04 GMT
Content-Type: application/xml
X-Total-Count: 56
Link: <https://www.osti.gov/elink/2416api?page=1&rows=25>; rel="next",<https://www.osti.gov/elink/2416api?page=2&rows=25>; rel="last"
...
                                    

Pagination

Requests that return multiple records will be paginated to 25 records by default; the number of records per page can be modified by specifying a numerical value for the ?rows parameter, and the specific page with the ?page parameter (default 0).

Response <records> tag attributes contain the number of rows found, as well as the requested starting row number, and rows per page values, as numfound, start, and rows respectively.

If additional pages of results are returned, the Link response header will contain applicable URL references in RFC 5988 format to additional pages, using the "rel" attributes indicated below.

Query Parameter Values
Name Description
rows Maximum number of desired rows per page, default of 25.
page Page number of results, if maximum exceeds the rows parameter. Numbering starts from 0.
Link Header Rel Values
Name Description
next Link to next page of results
last Link to last page of results
prev Link to previous page of results
first Link to first page of results

Example Link Header Values


$ curl https://www.osti.gov/elink/2416api?page=3&rows=25
                                                  
HTTP/1.1 200 OK

...
X-Total-Count: 679
Link: 
<https://www.osti.gov/elink/2416api?page=2&rows=25>; rel="prev",
<https://www.osti.gov/elink/2416api?page=0&rows=25>; rel="first",
<https://www.osti.gov/elink/2416api?page=4&rows=25>; rel="next",
<https://www.osti.gov/elink/2416api?page=27&rows=25>; rel="last"
...

<records numfound="679" start="50" rows="25">
...

Record Model

Responses returning data all return the same basic structure, formatted as appropriate for the content type requested.

HTTP Status Codes

A successful response from the API will always return an HTTP status code of 200.

HTTP Success Status
Status Description
200 OK

Record Fields

Results are always presented as a list of data defined as <record> elements wrapped in a <records> container. The attributes start will indicate the index of the first record in this set, rows indicates the number of rows per page, and numfound represents the total number of rows found.

Record Fields
Field Name Description
osti_idThe unique OSTI identifier for the record. Required for updates.
dataset_typeType of the main content of the dataset. Codes listed below.
titleFull title of the dataset, with version numbers and date ranges if applicable.
descriptionA short description or abstract
creatorsDataset creator names; format is last name, first name, middle initial, with multiple values separated by semi-colon. This is a string format. MAY NOT be used with specified with <authors> xml format details in the same record (deprecated format).
authorsDetailed set of information for person(s) responsible for creation of the dataset content. Allows transmission of ORCID information and more detailed affiliations (see below). MAY NOT be used in the same record as the string format, <creators>.
authorDetail information about a single creator, wrapped in the <authors> set above. (See below for more details.)
contributorsSet of contributor(s) to the dataset content, with contribution roles
contributorInformation about a particular contributor to the dataset content, with attribute contributorType specifying type of contribution (see below).
product_nosThe most important identifying numbers given to the dataset by the host or originating organization. Multiple values are separated by semicolon.
contract_nosPrimary DOE contract number(s), multiple values may be separated by semicolon.
product_typeThe product type of the record ("DA" for "Dataset")
doiPut a value in this field ONLY if the DOI has already been assigned by an organization other than OSTI.
doi_infixIf present, the site-selected DOI inset value for new DOIs.
publication_dateThe dataset publication date, in mm/dd/yyyy, yyyy, or yyyy Month format.
other_identifying_numbersAny alternative identifying numbers for this data set.
keywordsWords or phrases relevant to this data set. Multiple values may be separated by a semicolon and a following space.
countryThe country of publication for this dataset.
languageThe primary language of the dataset.
availabilityIf applicable, the office or organization to refer access requests to
originating_research_orgIf credited, the organization name primarily responsible for conducting the research
sponsor_orgIf credited, the organization name that sponsored / funded the research. For a list of sponsor organizations, see Sponsoring Organization Authority at https://www.osti.gov/elink/authorities.jsp. Multiple codes may be semi-colon delimited.
subject_categories_codeA two digit code and its controlled vocabulary term(s) that indicate the main subject topic of the dataset’s content. For codes, vocabulary, and detailed definitions, see Subject Categories Authority at https://www.osti.gov/elink/authorities.jsp. Multiple codes may be semi-colon delimited.
entry_dateThe date the record was added or last modified, in ISO-8601 format, generated by the system.
site_urlFull URL to the "landing page" for this data set
site_input_code(optional) The Site Code that owns this particular data set; will default to logged-in user's primary Site if not set. User must have appropriate privileges to submit records to this Site.
accession_numSite specific unique identifier for this data set.
descriptionAbstract or summary of the data set.
related_identifiersSet of related identifiers for this data (additional information below).
geolocationsSet of geolocation data, if any, for this data set (additional information below).
awardsInformation about any awards and award DOI for time awarded, etc. for this dataset (additional information below).
date_first_submittedDate first sent to OSTI, administrative purposes only.
date_last_submittedDate most recently submitted to OSTI, administrative purposes only.
file_extensionFile format pertaining to this data.
software_neededAny supplementary software programs for representing or interpreting this data.
contact_nameName of a contact person for this data set.
contact_phonePhone number for the contact.
contact_emailEmail address for the contact.
contact_orgThe organization or laboratory affiliation of the contact.
othnondoe_contract_nosAny non-DOE award numbers associated with this data set.
related_resourceFull bibliographic citation for the key paper the dataset supports.
collaboration_namesThis is a place to put names of collaborations, such as ATLAS, or similar types of organizations that significantly contributed to the existence of this dataset.
dataset_size(Optional) Indicate the approximate size in number of files, megabytes, or other appropriate metrics relevant to the data.
set_reservedIf a DOI is needed BEFORE the dataset and its landing page are available on the host website, use this tag to SAVE or RESERVE a DOI value. This will NOT be transmitted to DataCite, nor will it be resolvable until later updated without this tag.

Example Response

HTTP/1.1 200 OK
Content-Type: application/xml

<records start="0" rows="25" numfound="5334">
  <record status="Pending" released="N">
  <osti_id>1318659</osti_id>
  <dataset_type>SM</dataset_type>
  <title>Title of the data set</title>
  <authors>
    <author>
      <first_name>Author</first_name>
      <last_name>One</last_name>
      <private_email>oneguy@private.email.com</private_email>
    </author>
    <author>
      <first_name>Author</first_name>
      <last_name>Two</last_name>
    </author>
    <author>
      <first_name>Author</first_name>
      <last_name>Three</last_name>
    </author>
  </authors>
  <contributors>
    <contributor contributorType="DataCurator">
      <first_name>Testing</first_name>
      <last_name>Guy</last_name>
    </contributor>
  </contributors>
  <related_resource>Related Resource information</related_resource>
  <product_nos>product-001</product_nos>
  <product_type>DA</product_type>
  <contract_nos>DOE-CONTRACT-001</contract_nos>
  <other_identifying_numbers>01234</other_identifying_numbers>
  <originating_research_org>A Research University (United States)</originating_research_org>
  <availability>Direct paper publishing information</availability>
  <collaboration_names>Contributions Unlimited, LLC.</collaboration_names>
  <publication_date>2014</publication_date>
  <language>English</language>
  <country>US</country>
  <site_input_code>OSTI</site_input_code>
  <sponsor_org>USDOE Office of Science (SC)</sponsor_org>
  <subject_categories_code>Testing; Software; Data</subject_categories_code>
  <keywords>Data Sources; Measuring; Scientific Method</keywords>
  <accession_num>123456789</accession_num>
  <description>A simple abstract description of the data set and its research information.</description>
  <related_identifiers>
    <detail>
      <related_identifier>10.5072/0007</related_identifier>
      <related_identifier_type>DOI</related_identifier_type>
      <relation_type>IsPreviousVersionOf</relation_type>
    </detail>
    <detail>
      <related_identifier>10.5072/journal.2007.01529.x</related_identifier>
      <related_identifier_type>DOI</related_identifier_type>
      <relation_type>IsCompiledBy</relation_type>
    </detail>
  </related_identifiers>
  <geolocations>
    <geolocation>
      <place>In the Australian Outback</place>
      <point latitude="-22.839645" longitude="129.375000"/>
    </geolocation>
  </geolocations>
  <awards>
    <award>
      <award_doi>10.11578/92930</award_doi>
      <award_number>92930</award_number>
      <funder_name>Awarding Entity, Inc.</funder_name>
    </award>
  </awards>
  <date_first_submitted>2016-04-04</date_first_submitted>
  <date_last_submitted>2016-04-04</date_last_submitted>
  <doi status="PENDING">10.5072/DataScienceJournal/1318659</doi>
  <doi_infix>DataScienceJournal</doi_infix>
  <file_extension>xls</file_extension>
  <software_needed>Excel or other spreadsheet software</software_needed>
  <site_url>http://host.com/my_landing_page.html</site_url>
  <dataset_size>50 GB</dataset_size>
  <contact_name>Data User Services</contact_name>
  <contact_org>OSTI</contact_org>
  <contact_email>testing@osti.gov</contact_email>
  <contact_phone>888-241-5926</contact_phone>
  <othnondoe_contract_nos>NonDOEAwardNumber001</othnondoe_contract_nos>
  </record>
</records>

Creators and Contributors fields
Field Name Description
first_nameAuthor's first, or given, name.
middle_nameAuthor's middle name or initial, if supplied.
last_nameAuthor's last, or family, name.
affiliation_nameAn affiliation, if entered.
private_emailAuthor's email address.
orcid_idAuthor’s ORCID, if supplied. Only include the 16-digit number.
contributorTypeThe contribution type, attribute exclusive to contributors.

Example Creator Details


<authors>
<author>
  <first_name>Sample</first_name>
  <middle_name>Q.</middle_name>
  <last_name>Mann</last_name>
  <affiliation_name>Test Persons, Inc.</affiliation_name>
  <private_email>sampleguy@someplace.com</private_email>
  <orcid_id>0000111122223333</orcid_id>
</author>
<!-- optionally more details -->
</authors>
<!-- contributors are optional, but similar -->
<contributors>
<contributor contributorType="Researcher">
  <first_name>Jane</first_name>
  <last_name>Doe</last_name>
  <affiliation_name>Research Services, Inc.</affiliation_name>
</contributor>
</contributors>
Contributor Type Codes
Code Definition
ContactPersonPerson with knowledge of how to access, troubleshoot, or otherwise field issues related to the resource.
DataCollectorPerson/institution responsible for finding or gathering data under the guidelines of the author(s) or Principal Investigator.
DataCuratorPerson tasked with reviewing, enhancing, cleaning, or standardizing metadata and the associated data submitted.
DataManagerPerson (or organization with a staff of data managers, such as a data centre) responsible for maintaining the finished resource.
DistributorInstitution tasked with responsibility to generate/disseminate copies of the resource in either electronic or print form.
EditorA person who oversees the details related to the publication format of the resource.
HostingInstitutionThe organization allowing the resource to be available on the internet.
ProducerTypically a person or organization responsible for the artistry and form of a media product.
ProjectLeaderPerson officially designated as head of project team instrumental in the work necessary to development of the resource.
ProjectManagerPerson officially designated as manager of a project. Project may consist of one or many project teams and sub-teams.
ProjectMemberPerson on the membership list of a designated project/project team.
RegistrationAgencyInstitution officially appointed by a Registration Authority to handle specific tasks within a defined area of responsibility.
RegistrationAuthorityA standards-setting body from which Registration Agencies obtain official recognition and guidance.
RelatedPersonPerson with no specifically defined role in the development of the resource, but who is someone the author wishes to recognize.
ResearcherA person involved in analyzing data or the results of an experiment or formal study.
ResearchGroupRefers to a group of individuals with a lab, department, or division; the group has a particular, defined focus of activity.
RightsHolderPerson or institution owning or managing property rights, including intellectual property rights over the resource.
SponsorPerson or organization that issued a contract or under the auspices of which a work has been performed.
SupervisorDesignated administrator over one or more groups working to produce a resource or over one or more steps of development process.
WorkPackageLeaderA Work Package is a recognized data product, not all of which is included in publication.
OtherAny person or institution making a significant contribution, but whose contribution does not "fit".
Dataset Type Codes
Code Definition
ASAnimations/Simulations
GDGenome/Genetic Data (such as gene sequences)
IMInteractive data maps, such as GIS data and/or shape files
NDNumeric Data
IPStill images or photos
FPFigures/Plots, charts and diagrams
SMSpecialized Mix of differing data types
MMMultimedia, such as videos of experiments
IInstrument
Related Identifier Details
Tag Purpose/Description
detailTag encapsulating a single related identifier value.
related_identifierThe DOI of the related resource.
relation_typeA code specifying the type of relation between this identifier and the parent dataset. May be specified as the tag attribute "relationType" optionally.
related_identifier_typeThe type of identifier, usually "DOI". May be specified as tag attribute "relatedIdentifierType".

Example Related Identifiers Details


<related_identifiers>
<detail>
  <related_identifier>10.5072/238923</related_identifier>
  <relation_type>Cites</relation_type>
  <related_identifier_type>DOI</related_identifier_type>
</detail>
<detail relationType="References" relatedIdentifierType="DOI">
  <related_identifier>10.5072/science/2019/18-200</related_identifier>
</detail>
<!-- optionally more details -->
</related_identifiers>

Related Identifier Types
Code Description
DOIThe related identifier is a DOI
URLThe related identifier is a URL
Relation Types
Code Description
Citesindicates that A includes B in a citation
Compilesindicates B is the result of a compile or creation event using A
Continuesindicates A is a continuation of the work B
Documentsindicates A is documentation about/B
HasMetadataindicates resource A has additional metadata B
HasPartindicates A includes the part B
IsCitedByindicates that B includes A in a citation
IsCompiledByindicates B is used to compile or create A
IsContinuedByindicates A is continued by the work B
IsDerivedFromindicates B is a source upon which A is based
IsDocumentedByindicates B is documentation about/explaining A
IsIdenticalToindicates that A is identical to B, for use when there is a need to register two separate instances of the same resource
IsMetadataForindicates additional metadata A for a resource B
IsNewVersionOfindicates A is a new edition of B, where the new edition has been modified or updated
IsOriginalFormOfindicates A is the original form of B
IsPartOfindicates A is a portion of B; may be used for elements of a series
IsPreviousVersionOfindicates A is a previous edition of B
IsReferencedByindicates A is used as a source of information by B
IsReviewedByindicates that A is reviewed by B
IsSourceOfindicates A is a source upon which B is based
IsSupplementedByindicates that B is a supplement to A
IsSupplementToindicates that A is a supplement to B
IsObsoletedByindicates that A is obsoleted by B
Obsoletesindicates that A obsoletes B
IsVariantFormOfindicates A is a variant or different form of B, e.g. calculated or calibrated form or different packaging
Referencesindicates B is used as a source of information for A
Reviewsindicates that A is a review of B
Geolocation Detail Information
Tag Purpose/Description
geolocationsWrapper tag for all geolocation data.
geolocationWrapper tag for each individual geolocation data set.
placeOptional description of geolocation data in text form.
polygonA set of points making up a closed arbitrary polygon shape.
boundingBoxA square or rectangle shape defined by two sets of latitude and longitude data points.
pointA single geolocation point, represented by latitude and longitude values.

Example Geolocation Data


<geolocations>
  <geolocation>
    <place>Tennessee</place>
    <polygon>
      <point longitude="-81.6064453125" latitude="36.597889133070225"/>
      <point longitude="-88.04443359375" latitude="36.6507925250347"/>
      <point longitude="-88.06640625" latitude="36.491973470593685"/>
      <point longitude="-89.45068359375" latitude="36.4566360115962"/>
      <point longitude="-90.32958984375" latitude="34.994003757575776"/>
      <point longitude="-84.35302734375" latitude="35.02999636902566"/>
      <point longitude="-81.6064453125" latitude="36.597889133070225"/>
    </polygon>
  </geolocation>
  <geolocation>
    <place>Near Myrtle Beach, SC</place>
    <point longitude="-78.85986328125" latitude="33.72433966174761"/>
  </geolocation>
  <geolocation>
    <place>Around Atlanta, GA</place>
    <boundingBox>
      <westLongitude>-84.5233154296875</westLongitude>
      <eastLongitude>-84.287109375</eastLongitude>
      <northLatitude>33.85673152928873</northLatitude>
      <southLatitude>33.60546961227188</southLatitude>
    </boundingBox>
  </geolocation>
</geolocations>

                                        
                                    
Award DOI Detail Information
Tag Purpose/Description
awardsContain a set of one or more award elements.
awardDetail information for a particular award.
award_doiDigital Object Identifier assigned to this award.
award_numberFunder-specific identifier number for this award.
funder_nameName of funding entity or laboratory providing the award.

Example Award Data


<awards>
  <award>
    <award_doi>10.11578/award-2020/29300X</award_doi>
    <award_number>AW-29300X</award_number>
    <funder_name>Funding Entity LLC</funder_name>
  </award>
</awards>
           
                                    

Error Model

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.

HTTP Status Codes

Errors will be returned with an HTTP error status code appropriate to the type of error encountered.

HTTP Error Status
Status Description
400 Bad request
Usually indicates an XML parsing error or badly-formatted input parameters or search query terms.
401 Unauthorized
The user login supplied does not have sufficient privileges to access the information requested, or to post records to ELINK.
404 Resource Not Found
Requested record or resource is not on file at OSTI.
405 Method Not Allowed
PUT and DELETE methods are not currently implemented by ELINK 241.6 API.
500 Internal Error
An internal software error or database failure has occurred.

Endpoints

The ELINK 241.6 API currently supports a single endpoint, with the HTTP request method (GET or POST) determining the appropriate action. GET requests are information retrieval requests, while POST implies either new data creation or updating of current data sets.

API Root Endpoint

https://www.osti.gov/elink/2416api

Record List (Search)

GET

The record list endpoint allows you to search for lists of records in ELINK by a variety of criteria.

Record List Query Parameters
Parameter Description
osti_idThe unique OSTI identifier for a record
titleSearches within document titles
report_numberFinds records based on report number
doiSearch by a specific DOI
contract_numberSearch by DOE contract number value
site_unique_idSearch by site specific unique identifier, or accession number value
statusStatus of the records; one of complete, pending, or saved
publication_date_fromStarting publication date. All dates may be expressed in YYYY-MM-DD or MM/DD/YYYY format.
publication_date_toEnding publication date.
submit_date_fromStarting last submission date of records.
submit_date_toEnding last submission date.
rowsThe number of rows per page to return (default 25)
pageThe specific page of records to return (0-based, default 0, first page)

Record List Endpoint

https://www.osti.gov/elink/2416api

Data Submission

POST

Records may be submitted in XML format as defined above via a POST request made to the same endpoint. Updates to existing records must include the <osti_id> tag value of the record to be updated, while new records should omit the tag to get a newly assigned ID.

If no DOI tag is specified for a dataset record, one will be assigned and posted to the DataCite DOI registry based on the OSTI ID and any user-supplied <doi_infix> tag optionally presented. DOIs will be of the form: {site-specific-prefix}/{user-supplied-doi-infix}/{osti_id}

The service will respond with a summary of the submissions upon posting, with a status of SUCCESS or FAILURE for each submitted record in the order they were submitted.

Data Submission Endpoint

https://www.osti.gov/elink/2416api

Example SUCCESS submission response


<?xml version="1.0" encoding="UTF-8"?>
<records>
  <record>
    <osti_id>1328400</osti_id>
    <product_nos>MLM-2857</product_nos>
    <title>Testing Title</title>
    <contract_nos>NONE</contract_nos>
    <other_identifying_nos></other_identifying_nos>
    <status>SUCCESS</status>
    <status_message></status_message>
  </record>
</records>

Example FAILURE submission response


<?xml version="1.0" encoding="UTF-8"?>
<records>
  <record>
    <osti_id>0</osti_id>
    <product_nos>MLM-28393</product_nos>
    <title>Sample Title</title>
    <contract_nos>NONE</contract_nos>
    <other_identifying_nos></other_identifying_nos>
    <status>FAILURE</status>
    <status_message>Access denied.  testuser3 cannot release records for SITE</status_message>
  </record>
</records>