Digital Commons API: Getting Started

Find answers to basic questions about the Digital Commons Outbound API below. See our API documentation when you’re ready to dive in.

What Is the Digital Commons API?

The Digital Commons Outbound API (Application Programming Interface) is a way to directly access your repository’s data in order to share and include your content in other places. Site visitors already enjoy that content through the UI (User Interface) of your repository or journal. With the API, you get secure access to the same records in computer-readable form, which helps library and IT staff more easily build applications and integrate with other systems.

Even if you already use methods such as OAI or RSS to harness Digital Commons content elsewhere, the API may help you streamline the process or overcome technical barriers to branching out. The result is a broader tool set for your repository to expand the reach and impact of institutional output.

What Does the API Provide?

The API enables you to retrieve any or all of the following:

  • A full metadata snapshot of your repository, refreshed monthly
  • An incremental update snapshot with changes from the previous month
  • Filtered snapshots with search-based parameters that you define, including support for filters based on institutional author ID

You have unlimited access to your data via the API, which returns results in JSON—a flexible and lightweight file format that plays well with lots of different programming options. When you download the JSON file, it contains metadata for all matching records and is ready to employ in a variety of contexts.

What Can You Do with the API?

Using the API, you and your team can automatically extract data in order to power integration with other systems and programs. Applications range from displaying content on a website to streamlining metadata for cross-platform use to building web apps. The cloud’s the limit!

API output gives you greater flexibility to:

  • Support interoperability with other products and services, such as ingesting Digital Commons data into faculty reporting systems like Faculty 180 and Digital Measures
  • Increase discoverability by sending data to institutional, departmental, and faculty websites
  • Manipulate data from your site to perform text mining and metadata analysis
  • Provide metadata to aggregators and portals including DOAJ and CrossRef
  • Partner with more stakeholders like your Web/IT group, Marketing teams, and the Office of the Provost
  • Innovate creative approaches to sharing and reimagining your content!

How Do You Start Using the API?

The first step is to contact Consulting Services to obtain an API key and security token. These are required to access the API for your site.

To make API calls, you can use your programming language of choice or an HTTP client such as Postman, Insomnia, or HTTPie. The documentation (view PDF) links to these and includes information about generating requests using Postman. You’ll also find copy-friendly sample code for common request types.

Whichever tool(s) you use, the basic principles are the same:

  • The Digital Commons API is built around REST, which means it uses HTTP commands and URLs similar to the ones used for accessing pages in a web browser.
  • Instead of using a browser, you’ll build a program to call those URLs automatically to obtain their machine-readable content.
  • The API consists of a base URL and variables called endpoints that you tack on to access the data you want to retrieve. Some endpoints allow you to create and call your own search-based filters.
  • In the end, what you get back is not an HTML browser page, but a JSON file that can be parsed into your website or application.

Once you 1) obtain your API key and security token, 2) review the documentation, and 3) choose your tool(s), you’ll be ready to make API requests.

Example of an API Request

The most basic request is to retrieve all records for your site. Starting from scratch, the process includes these steps:

  1. Obtain your API key and security token from Consulting Services (dc-support@cs.bepress.com) and review the API documentation (view PDF). Also, make sure you’re set up to use an HTTP client or preferred programming language.
  2. Combine the base URL and the endpoint found in the documentation for a full site snapshot:

    https://content-out.bepress.com/v1   +   /results/latest/YOUR_SITE_URL

    Replace YOUR_SITE_URL with your repository’s URL minus the https://.

    Request as entered in Postman (an HTTP client)

      • Include your API key and security token in the headers of the API request.
      • If you want narrower results, you can create a search-based filter using a different endpoint and adding search parameters in the body of the request (see documentation). Filters can target any metadata field and any publication structure.
  3. Make a GET request to retrieve your results. (In Postman, select “GET”, then click “Send”.)
  4. Receive a response from the API containing a link. The link is the location of a JSON file with records matching the request. You’ll use the link to download the file and access the requested records.

Using Institutional Author IDs with the API

In addition to search-based filters that can target any metadata field, including author name, the API allows you to create filters based on author ID. This may be helpful if you need to disambiguate authors when pulling results to display on a faculty web page, for instance, or to ingest into a faculty activity reporting system.

Instructions in the documentation (view PDF) walk step by step through the process of associating institutional IDs—or other identifiers such as ORCID ID—with author metadata. Once you’ve added one or more IDs to get the best author results possible, you can then build filters to call the API using any of those IDs.

Comparison of the DC API with Other DC Data Delivery Methods

How does the API compare with other methods of exporting or pushing content out of Digital Commons? The comparison chart below can help you evaluate where the API’s capabilities might add support for your workflows.

Method Output Type Contents Supports Queries Access Update Frequency Common Uses
API JSON All Metadata (including hidden) Yes API key and security token Monthly (version 1) Institutional and departmental webpages; faculty webpages; faculty reporting systems; text mining, metadata analysis, building web apps; output for DOAJ, CrossRef
OAI XML Mapped metadata (including hidden) Yes Public Daily Discovery platforms; online libraries and databases; harvesters; OpenAire
RSS RSS Limited metadata (requires customization to expand) No Public Varies Institutional and departmental webpages; faculty webpages; displaying recent content lists
Content Inventory Excel Any or all metadata (including hidden) No Administrator permissions Daily Reporting
Batch Export Excel All metadata in a specific structure (including hidden) No Administrator permissions Returns current data Reporting; submission and metadata management

FAQs

Where can I find documentation for the API?

The Digital Commons API Documentation (PDF) provides detailed information and steps for using the API.

Can I request a separate security token for someone else at my institution?

Definitely. You are able to request multiple tokens for different people on your team or in other departments. Tokens can be generated or revoked at any time by contacting Consulting Services.

Who can I contact if I have questions about using the API?

Please contact Consulting Services at dc-support@cs.bepress.com, or 510-665-1200 (option 2), Monday-Friday, 6:30 a.m. to 7:30 p.m. North American Pacific time.

Files