Find answers below to basic questions about the Digital Commons Outbound API, version 2. See our full version 2 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.

Key Features

• A straightforward query format that uses Solr-based field search criteria
• All available metadata or subsets of metadata for all matching records
• Results in JSON—a flexible and lightweight file format that plays well with lots of different programming options
• Unlimited access to your data via the API

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 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 to Start Using the API

The first step to start using the API is to contact Consulting Services to obtain a security token. This is 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 API documentation links to these and includes information about generating requests using Postman.

Whichever tool(s) you use, the 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 with your query to access the data you want to retrieve.
• 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 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

One of the most basic requests is a free form text query across metadata fields, with results that include all available fields. Starting from scratch, the process includes these steps:

1. Obtain your security token from Consulting Services and review the API documentation. Also, make sure you’re set up to use an HTTP client or preferred programming language.
2. Combine the base URL with your site URL, then add the endpoint and query (found in the documentation) for free form text:

https://content-out.bepress.com/v2/ + {site_url} + /query?q=video

Replace {site_url} with your repository’s URL minus the https://.

Request as entered in Postman (an HTTP client)

• If you want narrower results, you can choose additional parameters (see documentation) to restrict attributes such as fields searched and/or fields returned. Queries can target any available metadata field and any publication structure.
• Include your security token in the headers of the API request.

1. Make a GET request to retrieve your results. (In Postman, select “GET”, then click “Send”.)
2. Receive a response from the API containing a JSON file with records matching the request. Download the response file.

Comparison of Data Delivery Methods in DC

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.

FAQs

Where can I find documentation for the API?

The Digital Commons API Documentation provides detailed information and steps for using the API v2. (Documentation for v1 (PDF) is still available as well.)

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 with any questions.