PMP Technical Upgrades for 2017

Dec 30, 2016

As many of you know, NPR has been working to replace the much loved and used Story API with an enhanced version of the Public Media Platform. Our goal remains--this new API will serve as a central repository for all public media content, including content from NPR, its member stations, and other public media organizations. NPR will utilize this new API for its own digital content distribution, replacing the existing Story API as the technology that distributes content to all digital properties. This process ensures the API will be performant and support features that matter to a broad range of organizations.

 

 

What’s changing in the new version of PMP?

Our team is excited to be working on some architectural and feature improvements in the new version of PMP, building off of the strong foundation provided by the current version of the Public Media Platform. We are staying true to the overall design principles of a hypermedia API, but this post outlines some of the updates we are planning, including a move to the HAL+JSON media type to define and structure the API’s content.

 

What does this mean for me?

If you use Core Publisher or one of Digital Services’ provided plugins or modules to interact with the PMP, you will not need to do anything to accommodate these changes, but you may be interested to read on to learn more about what improvements these updates will offer.

If you and your team have programmed your own integration with the PMP, there will be some code changes needed to migrate your client applications to the new verison. Technical documentation will be provided by NPR closer to our “go live” date in the fall of 2017, but the sections below offer a general outline of what updates will be necessary.

Move to the HAL+JSON Media Type

What’s changing?

One of the most important decisions to make when designing an API is selecting which media type will be used to standardize the data structure of your content. One noticeable change in is our shift from using the Collection.DOC (CDoc) +JSON media type to the Hypertext Application Language (HAL) +JSON media type.

Why the change?

The HAL+JSON media type offers the following advantages:

  • Better handling of embedded resources; a useful benefit since PMP stories often include associate audio, video, and image assets.

  • Clearer specifications for building a solution to handle content permissions.

  • Stronger developer community, giving users access to more open source libraries and other implementation resources.

What does this mean for my integration with the new version?

The data structure of your content will need to be modified to match HAL specifications, and your client applications will need to be updated to expect HAL-structured documents to be returned in API server responses.

Relative URLs

What’s changing?

PMP requires absolute URLs, meaning that a link must include the complete path to a resource, including the server and domain information; for example, "http://api.npr.org/docs/{guid}". In the new version we are adding support for relative URLs, which need only define the path to the resource; for example, "/docs/{guid}").

Why the change?

Relative URLs allow links within the API to be specified to a given server environment as needed. For example, a relative URL can be directed to a testing server versus a production server. This change will also prove helpful down the line if the decision is made to support "draft" versus "published" domains. In addition, support for relative URLs will allow users of the new version to reference resources that are only found within a parent document, such as an embedded audio or image asset, making it easier for the API to communicate relevant layout data to clients.

What does this mean for my integration with the new version?

Clients will no longer be able to assume that any URL they receive is an absolute URL; documentation will be provided on the necessary prefix for a given environment.

Changes to Publishing a Document

What’s changing?

Most of the changes to publishing a document in the new version will reflect our shift to the HAL media type (as described above). But in addition, there will be a few changes related to attributes and naming conventions.

Why the change?

Most of these changes are intended to make our naming conventions more standardized and consistent, and facilitate a smooth transition to using the HAL media type.

What does this mean for my integration with the new version?

A detailed publishing spec will be provided, which we will strongly encourage publishers to follow so that their content can be discoverable within the API and useable by other API consumers.

Changes to Search Queries

What’s changing?

In an effort to remove redundancy and move into fuller compliance with best practices, the team has made the following changes to the new version's search functionality:

  • Removed search query field aliases to make sure that query fields will correspond directly to the searchable fields in the indexed documents.

  • Moved support for Lucene query syntax to the "advanced" search option.

  • Reverted the "text" query field to support full-text search, and added support for "and"/"or" operators.

Why the change?

These updates will allow for smoother troubleshooting for developers, while enabling a more intuitive search experience for users and more consistent API performance.

What does this mean for my integration with the new version?

Any automated client-side queries will need to be updated to reflect these changes; documentation will be provided on how to reformat these queries.