Developer Hub

Purpose

Details below provide documentation of services OSTI has created to facilitate the transition from E-Link 1 to 2, as well as examples of changes made to the submission APIs, with some background information behind those changes. The API specification has undergone a number of changes in the rewrite, not the least of which being a shift from XML-based submissions to JSON. Additionally, a number of organizational design changes have been adopted in order to organize metadata elements, and adapt to new technologies.

In E-Link 1, there exist two separate XML ingest formats: one for data sets (241.6 API) and another similar but different format for other product types (241.1 API). These two separate XML formats differed enough in design, tag names, requirements, methodologies, and endpoints to warrant a burden on users of the system, especially those requiring submission of both types of metadata. Having two separate ingest formats also caused duplication of effort on OSTI's part to address bugfixes, security maintenance, and other concerns, as well as requiring extra training and support documentation whenever one or both formats changed.

Having separate requirements, tags, and support documentation for two separate but functionally similar systems led to the desire to consolidate both designs into a single API for all product types. Some of the main relevant changes are detailed below, with some information as to why the changes were made.

Guides and Resources

Notes on Batch Submission Processing

The API for E-Link 2 has been implemented following generally accepted REST API procedures; that is to say, meant to operate on a single record at a time. There are numerous reasons behind this change, not least of which is to accommodate service scaling, as large batches of records as a single request tie up the system and cannot be routed as efficiently as numerous single record requests may. Additionally, the single record operation (POST, PUT, etc.) allow the user to interpret immediate success or failure of the operation; e.g., a 200 or 201 response indicating success, with a 400 or other error message with detailed information can be handled without the additional wait time to receive and parse a lengthy batch response for such information. It is recommended that users may modify their processes to implement a simple loop over each record request, obtaining pass or fail iteratively over the entire set. This also tends to reduce instances of syntax errors one might encounter in a large batch submission, which cause the operation to fail entirely.