Find answers below to basic questions about the Digital Commons Outbound API, version 1. See our full version 1 API documentation when you’re ready to dive in. (Initial instructions for version 2 are now available as well.)
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:
- Obtain your API key and security token from Consulting Services (firstname.lastname@example.org) and review the API documentation (view PDF). Also, make sure you’re set up to use an HTTP client or preferred programming language.
- Combine the base URL and the endpoint found in the documentation for a full site snapshot:
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.
- Make a GET request to retrieve your results. (In Postman, select “GET”, then click “Send”.)
- 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.
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|