Skip Navigation Bar
National Library of Medicine Technical BulletinNational Library of Medicine Technical Bulletin

Table of Contents: 2024 MARCH–APRIL No. 457

Previous Next API Version 2.0 Now Available API Version 2.0 Now Available. 2024 Mar-Apr;(457):e2.

2024 March 19 [posted]

The API version 2.0 is now available on the modernized website. The API, or application programming interface, is a tool to help researchers and developers access the data in study records. This new version differs from the legacy API on the classic website in important ways, some of which we highlight below.

The API version 2.0 is a REST API and uses the OpenAPI Specification 3.0 to describe its meta information. This approach has the following benefits:

  • Allows the support of third-party OpenAPI 3.0 libraries and applications that rely on the API to build customized interfaces and workflows.
  • Aligns with standard expectations for publicly accessible modern APIs.

Specific differences in how data are handled by the new API include:

  • Standardizing and changing the data type of certain fields (e.g., Intervention Type) from text to enumurated values, meaning users can choose from a set of values.
  • Standardizing number fields.
  • Using the ISO 8601 format for dates.
  • Using the CommonMark Markdown format for rich-text data.
  • Using JSON as the primary response data.

The benefits of these changes for API users include:

  • Reducing the data transformation burden.
  • Reducing the validation burden.
  • Allowing users to more readily predict, consume, and use rich-text data.
  • Meeting users' expectations for data from publicly accessible, modern APIs.

To support users as they transition to the modernized API, we have provided support documentation such as a Migration Guide, which discusses the differences between the classic API and the API version 2.0. It also covers how legacy endpoints are supported through the modernized API. Additional documentation includes:

  • Study Data Structure.
  • Search Areas.
  • CSV Download.

Beginning in April, users may experience brief disruptions in legacy API services during a series of planned outages. Users are strongly encouraged to migrate to the new API as soon as possible. The classic API will be retired in June 2024. For more information on the new API, please see About the API on the modernized website.

screenshot of API Migration Guide including left-hand navigation menu listing Introduction, Info API Endpoints, Qurey API Endpoints, Other Endpoints, and Study Data Model.
Figure 1: An API Migration Guide is available on the website for additional support.

screenshot of the About the API webpage, including the link to the API Migration Guide at the top of the page.
Figure 2: Additional information about the new API is available on the modernized website.

NLM Technical Bulletin National Library of Medicine National Institutes of Health