API Basics

What’s an API?

At its most basic, an API, or Application Programming Interface, is made up of a set of defined methods that someone can use to communicate with a (frequently complex) software system, and get back responses in a way that a computer (and, with some practice, a human) can understand.

In essence, an API defines the ‘language’ a system speaks. Like a language, it has its own vocabulary with terms that have special meanings (e.g., property names and labels), grammar (how those property names and labels are arranged—collectively, its schema), and syntax (i.e., how the information itself is arranged). Like a language, you can use it to ask questions and understand responses. And like a language, with a little practice, it can be a powerful and extensible tool for communication.

A request is a URL sent to the web server over HTTP with the expectation of getting resource items back in the form of human-readable text or data. The URL supplies the web server with everything it needs to create and return a correct response. This is called a RESTful approach to API design and is employed by the DPLA API.

Who should use this?

This API is intended for use by large organizations and lone individuals alike, and our audience’s level of technical sophistication is deliberately quite varied.

How do I use it?

All you need to do to use the DPLA API is:

Request an API key from DPLA.
Fire up your web browser and enter your request into the URL bar.
Read the response.

The DPLA API offers metadata (and meta-metadata) on two types of resources: items and collections. In short, items represent single physical objects indexed by a DPLA data provider, and collections are logical groupings of items. For simplicity’s sake, let’s try a simple search for items—i.e., a full-text search of all of the fields associated with items for a single term.

Let’s say you really want to know more about weasels. Compose your search query by taking the URL of the API and append your request to it like so:

https://api.dp.la/v2/items?q=weasels&api_key=

https://api.dp.la/v2 specifies the API and the correct version; items indicates the type of resource you’re requesting; ?q= begins your request, and the unadorned, unqualified search term weasels will be interpreted as a request for a full-text search. The /v2 part of the request is optional, but ensures that you’re always hitting the same version of the API.

Remember: You must enter your 32-character API key after the &api_key= parameter in every example request, and in general.

Now let’s look at typical results (to simplify things, we’re only reproducing the first result here):

{
  count: 8,
  start: 0,
  limit: 10,
  docs: [
  {
      ingestDate: "2013-03-27T15:56:04.841413",
      _rev: "1-b9eb1deb8349347b8eea74a3c2bb4c42",
      id: "ff13fd51e7f2d38ef3fab8888be38bba",
      @context: {
        edm: "http://www.europeana.eu/schemas/edm/",
        isShownAt: "edm:isShownAt",
        dpla: "http://dp.la/terms/",
        dataProvider: "edm:dataProvider",
        aggregatedDigitalResource: "dpla:aggregatedDigitalResource",
        state: "dpla:state",
        hasView: "edm:hasView",
        provider: "edm:provider",
        collection: "dpla:aggregation",
        object: "edm:object",
        stateLocatedIn: "dpla:stateLocatedIn",
        begin: {
          @type: "xsd:date",
          @id: "dpla:dateRangeStart"
        },
        @vocab: "http://purl.org/dc/terms/",
        LCSH: "http://id.loc.gov/authorities/subjects",
        sourceResource: "edm:sourceResource",
        name: "xsd:string",
        coordinates: "dpla:coordinates",
        end: {
          @type: "xsd:date",
          @id: "dpla:dateRangeEnd"
        },
        originalRecord: "dpla:originalRecord"
    },
    isShownAt: "http://www.biodiversitylibrary.org/item/85666",
    _id: "bhl--http://www.biodiversitylibrary.org/item/85666",
    dataProvider: "Canadiana.org (archive.org)",
    sourceResource: {
        title: "Synopsis of the weasels of North America C. Hart Merriam",
        subject: [
          {
            name: "Mammals"
          },
          {
            name: "North America"
          },
          {
            name: "Weasels"
          }
      ],
      description: "",
      format: "Book",
      language: {
          name: "English"
      },
      type: "text",
      publisher: "Washington :G.P.O.,1896",
      creator: "Merriam, C. Hart (Clinton Hart), 1855-1942"
  },
  provider: {
    @id: "http://dp.la/api/contributor/bhl",
    name: "Biodiversity Heritage Library"
  },
  ingestType: "item",
  @id: "http://dp.la/api/items/ff13fd51e7f2d38ef3fab8888be38bba",
  collection: {
      title: "Volumes",
      @id: "http://dp.la/api/collections/bhl--C(",
      name: "Canadiana.org (archive.org)"
  },
  originalRecord: {
    id: "oai:biodiversitylibrary.org:item/85666",
    title: "Synopsis of the weasels of North America C. Hart Merriam.",
    handle: "http://www.biodiversitylibrary.org/item/85666",
    setSpec: "item",
    contributor: "Canadiana.org (archive.org)",
    description: "",
    subject: [
      "Mammals",
      "North America",
      "Weasels"
  ],
  datestamp: "2012-06-29T15:10:49Z",
  label: "Synopsis of the weasels of North America C. Hart Merriam.",
  language: "English",
  type: [
      "text",
      "Book"
  ],
  creator: "Merriam, C. Hart (Clinton Hart), 1855-1942",
  publisher: "Washington :G.P.O.,1896."
  },
score: 2.0859802
},
],
facets: [ ]
}

Oof! That’s a lot of data (and we’re not even showing you the other seven results!), but let’s dig into it a bit. A few things might jump out at you:

The record begins by specifying the count of the results (here, 8).
We can see that the results have been limited to 10.
For each item, the parent object docs contains information about how that item was imported into the database: for example, ingestDate and other context about the record (see @context).
Down in the sourceResource object, there’s information about the title and subject of the work. Here, the enumerated subject name: "Weasels" probably accounts for this being the first result.
We can see that the provider of this information (which DPLA has aggregated) is the Biodiversity Heritage Library.

This is just a dip into the well of information that this record alone contains. For more advanced querying and data interpretation, see the full documentation on requests and responses.