API Documentation

Summary

Wavelength has a powerful index offering rich search and discovery of professionally vetted educational materials created by NASA. Wavelength’s uses a simple and widely adopted standard, Atom, to make its search and discovery services available for:

  • Notifications and updates of new content, through custom filtered and selected feeds. You can use these Feeds with any Feed reader or many mobile apps.
  • Augmenting your own website with content organized by Wavelength. You can use Wavelength Feeds to automatically add continually updating links of vetted educational content to your blog, or other content-management system.

Navigation

Introduction

The World Wide Web represents one of the most profound developments in information sharing since the origins of writing. In the past 25 years, it has radically transformed communication in all walks of life. Nasawavelength project strives to use important principles of Web architecture to allow the broadest community to build upon Wavelength and its services.

Wavelength has two APIs (application program interfaces) that enable third parties to access to search and query results. These APIs respond to search requests in:

      Atom Syndication Format
      JSON (Javascript Object Notation)

    In this document, we describe how to use the open and standards-based APIs (Atom feeds and JSON services) to bring up-to-date and relevant NASA content organized and indexed by Wavelength into any Web-site.

    Website Creators: Why Use Wavelength APIs?

    Wavelength has APIs that allow its rich index to flow freely across the Web, into different services, and into special apps on a mobile device. Many people prefer using tablets (like an iPad or Android device) to browse and read content of interest. Wavelength’s Atom feeds can be consumed by popular mobile apps like Flipboard, which can display the educational materials organized and vetted by Wavelength in a magazine like format.

    In addition, the Web has a rich ecosystem of services that use Atom Feeds to help users keep up to date with new information. Wavelength’s Atom Feeds can be used with popular feed aggregator services like Feedly, which will automatically notify users of new content that matches their customized search preferences from Wavelength.

    Website Creators: Why Use Wavelength APIs? (Part 2)

    Wavelength maintains a rich and growing index of NASA educational and public outreach materials. Wavelength digital librarians have classified these materials according to their intended audience, their subject matters, curriculum standards, and much more. Moreover, Wavelength’s index continually grows. Wavelength’s APIs help share up-to-date search and discovery services for these materials.

    Here are some ways you can use Wavelength APIs to augment your own website:

    • Highlight professionally curated and described content published by your organization.
    • Supplement your content with vetted and relevant content published by other NASA units
    • Encourage user engagement by highlighting custom-defined feeds of content

    Wavelength’s Atom API

    Atom is a popular XML format used by many Websites, especially blogs, to syndicate content. Just as standardized shipping containers revolutionized international trade, Atom acts as a standard container to make it easy to package and share items of content across the Web. Wavelength uses Atom to share search and query results using this widely understood and widely supported format.

    Wavelength provides a URL to the Atom representation of all search results. For instance, one can search Wavelength for resources appropriate for “Informal Education” about “Stars, Nebulae, and Galaxies”. The URL for this search is as follows:

    The Web page showing those search results also provides a link to the Atom feed expression of the same results:

    The Atom representation includes information useful for third-parties in using and navigating the search results. Essentially, Atom provides a widely understood standard for sharing lists of resources, along with some useful metadata (descriptive information) about those resources. Wavelength Atom feeds have information describing the entire set of search results and information describing each individual resource found in a search. For more details about the information in the Wavelength Atom feeds, click here [link to Atom Feed Metadata Documentation].

    Putting Wavelength Atom Feeds in Your Website

    There are two main ways to use Wavelength Atom feeds in your website. You can work with the Atom feeds server-side by fetching and processing Wavelength Atom feeds on your own server, or you can create web-pages with javascript code for using Wavelength Atom feeds client-side (on user’s browsers). Each approach has advantages and disadvantages.

    Server-side (your server gets and processes Atom feeds from Wavelength) Advantage:

    Some users work with older browsers or disable javascript needed to process Atom feeds on the client side. Processing the Atom feeds server side lets you present information from the Wavelength Atom feeds as plain HTML which can be easily rendered on any browser.

    Most content popular content management systems (Wordpress, Drupal, etc.) already have many, many Atom-feed plugins that can be used to add Wavelength’s Atom feeds to your website.

    Disadvantage:

    It takes time for the server at your website to fetch the Atom feed data from Wavelength. This will make your website slower. To mitigate this problem, your server should periodically cache the Atom feed data locally, so it doesn’t have to wait for data from the Wavelength server.

    Resources:

    Wavelength generates Atom feeds because Atom is a very widely supported standard. Here are some links to widgets and plugins you can use to incorporate Wavelength content into your websites:

    • Wordpress (http://wordpress.org/plugins/search.php?q=atom+feed&sort=popular)
    • Drupal (https://drupal.org/project/feeds)
    • Plone (http://plone.org/products/collective.geo.opensearch http://plone.org/products/feedfeeder)
    Client-side (your server returns web-pages with javascript that fetches and processes Wavelength Atom feeds on the user’s browser) Advantages:

    Some people maintain websites but lack the skills or administrative privileges needed to alter source code on the servers. It is often easier to add some javascript to the HTML you publish. That javascript code can read, process, and display information from Wavelength Atom feeds.

    Disadvantage:

    Some web browsers may have javascript disabled or may be outdated and cannot run the javascript.

    Resources:

    There are several free and/or open source Javascript libraries that one can install for reading and displaying Atom feeds. Here are a few of the more popular choices:

    • FeedEk (jQuery based, https://github.com/enginkizil/FeedEk)
    • Google Feed API (free but Google may turn off this service, https://developers.google.com/feed/)

    Playgrounds to Help in Using Atom Feeds

    Because Atom feeds are so widely used, there are many, many tutorials and tools you can use as guides to using Wavelength’s feeds. Here is a short list of javascript playgrounds that can help in installing Wavelength feeds into your website:

    • Google Feed API playground (https://code.google.com/apis/ajax/playground/#load_feed)
    • Feed2JS.org has a very simple utility for testing javascript configurations (http://feed2js.org/index.php?s=build)
    • FeedEk is a powerful open-source javascript library for using Atom feeds. You can test it here (http://jquery-plugins.net/FeedEk/FeedEk_demo.html) and get the source-code here (https://github.com/enginkizil/FeedEk).

    Wavelength JSON Services

    Wavelength also offers JSON (javascript object notation) services that permit third-party access to machine readable data. JSON is very popular with developers. For Wavelength, the JSON service provides a more comprehensive and complete representation of Wavelength’s search results than the Atom service. The disadvantage with the JSON service is that developers will need to write customized code to interact with the JSON service, whereas the Atom service can be used immediately with “off-the-shelf” components and minimal configuration. To access the JSON service, simply take a url to a Wavelength Atom feed and replace “cow-facets-atom” with “cow-facets-json.”

    see example: