API Codex

Policies

API CODEX


» Codex Home
» API Basics
» Requests
» Responses
 »  Object Structure
 »  Field Reference
» Glossary
Policies
» Philosophy
» Technologies
» Troubleshooting & FAQ
 »  Issue Tracker
» Contact

API Keys

In order to access the DPLA API, you must first request an API key. The DPLA API key is a 32-character string that uniquely identifies you to the DPLA API servers.

How to get one

To request an API key, you must send a HTTP POST request to the following URL:

http://api.dp.la/v2/api_key/YOUR_EMAIL@example.com

where YOUR_EMAIL@example.com is the e-mail address with which you wish to associate your or your organization’s API usage.

You can send a POST request of this sort using curl, a free and open-source utility installed by default in all modern versions of Linux, BSD, and Mac OS X.

You may use the following command:

curl -v -XPOST http://api.dp.la/v2/api_key/YOUR_EMAIL@example.com

You will receive the following output:

< HTTP/1.1 201 Created
< Server: nginx
< Date: Wed, XX Apr XXXX XX:XX:XX GMT
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< X-Rack-Cache: invalidate, pass
< Cache-Control: max-age=0, private, must-revalidate
< Status: 201 Created
< X-Request-Id: f87dfea7c11d756255680d92307797bf
< X-Runtime: 1.004307
< ETag: "78586ee12b91811f2f26921b03d99027"
< X-UA-Compatible: IE=Edge,chrome=1
< 
* Connection #0 to host api.dp.la left intact
{"message":"API key created and sent via email"}* Closing connection #0

The API key will then be sent to the e-mail address you provided. To successfully query the API, you must include the ?api_key= parameter with the 32-character hash following.

What we use it for

When you request an API key, DPLA captures only your e-mail address. As a general rule, DPLA will use this e-mail address only for purposes of aggregate usage monitoring and urgent API-related notifications, including scenarios involving activity tending to compromise the availability of the API to others. Also, like virtually all other web services, the DPLA keeps access logs that may contain request parameters and the IP addresses from which requests originate.

Revocation

As part of the DPLA’s presumption of openness, access to the API will not ordinarily be rate-limited or revoked. The DPLA reserves the right to limit or revoke access to the API if, in its discretion, a user engages in abusive conduct, conduct that materially degrades the ability of other users to query the API.

Uptime and Availability

DPLA is committed to achieving the highest level of reliability possible for its API users, and hosts the API on highly available cloud infrastructure. While DPLA will make every effort to keep the API up and accessible to its users, and will take any steps it deems necessary to ensure that API users do not consume an unreasonable amount of shared resources, it provides the API on a “best effort” basis.

Versioning Policy

This documentation covers the second version of the DPLA API. From time to time, the DPLA may discontinue past APIs or deploy new ones that may obsolete previous versions. API users will receive notice of any version changes.

Schema Update Policy

From time to time, the DPLA may need to update or amend the API schema. API users will be notified of any changes made and of any elements of the schema that are to be deprecated and/or removed.

Limitations on Use

Consistent with its philosophical presumption of openness, in general, the DPLA will not restrict or rate-limit the use of its API. However, the DPLA reserves the right to protect the integrity of the API and the data it dispenses from abuse (in its discretion), particularly activity that has the effect of denying or unduly degrading service to other API users.

Technologies

How do we do the things we do? These are the technologies we use to build and maintain the API.

Philosophy

Why do we do the things we do? The DPLA API is meant to embody these principles.