From d622a9c82cc6c0e3bf236a3ea24047b3663fea4d Mon Sep 17 00:00:00 2001 From: Kathryn Mazaitis Date: Tue, 2 May 2023 16:53:33 -0400 Subject: [PATCH 1/4] Add API Keys documentation --- docs/api/README.md | 2 +- docs/api/api_keys.md | 35 ++++++++++++++++++ docs/api/covidcast.md | 2 +- docs/api/privacy_statement.md | 70 +++++++++++++++++++++++++++++++++++ docs/epidata_development.md | 2 +- docs/index.md | 19 ++++++++++ docs/new_endpoint_tutorial.md | 2 +- docs/symptom-survey/index.md | 2 +- 8 files changed, 129 insertions(+), 5 deletions(-) create mode 100644 docs/api/api_keys.md create mode 100644 docs/api/privacy_statement.md diff --git a/docs/api/README.md b/docs/api/README.md index f2be98f34..add09fd98 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,6 +1,6 @@ --- title: Other Endpoints (COVID-19 and Other Diseases) -nav_order: 2 +nav_order: 3 has_children: true --- diff --git a/docs/api/api_keys.md b/docs/api/api_keys.md new file mode 100644 index 000000000..c6744f441 --- /dev/null +++ b/docs/api/api_keys.md @@ -0,0 +1,35 @@ +--- +title: API Keys +nav_order: 2 +has_children: true +--- + +# Epidata API Keys + +Anyone may access the Epidata API anonymously without providing any personal +data. If you choose to [register for an API key](https://forms.gle/hkBr5SfQgxguAfEt7), +there are several ways to use your key to authenticate your requests: + +## Via request parameter + +The request parameter “api_key” can be used to pass the API key to the server. +Example: + + http://delphi.cmu.edu/epidata/covidcast/meta?api_key=your_api_key_here + +## Via Basic Authentication + +Another method is using the HTTP basic authorization header with the username +"epidata" and the API key as the password. Example: + +``` +curl -u 'epidata:your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta +``` + +## Via Bearer Token + +Another method is providing the key in a bearer token header. Example: + +``` +curl -H 'Authorization: Bearer your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta +``` diff --git a/docs/api/covidcast.md b/docs/api/covidcast.md index ddfce9c06..c1cb625a2 100644 --- a/docs/api/covidcast.md +++ b/docs/api/covidcast.md @@ -1,7 +1,7 @@ --- title: COVIDcast Main Endpoint has_children: true -nav_order: 1 +nav_order: 2 --- # COVIDcast Epidata API diff --git a/docs/api/privacy_statement.md b/docs/api/privacy_statement.md new file mode 100644 index 000000000..e3b08352e --- /dev/null +++ b/docs/api/privacy_statement.md @@ -0,0 +1,70 @@ +--- +title: Privacy Statement +parent: API Keys +--- + +# Delphi Privacy Statement + +Anyone may access the Epidata API anonymously without providing any personal +data. Anonymous API access is subject to the following restrictions: + +1. public datasets only +1. rate-limited to $RATE_LIMIT +1. only two parameters may have multiple selections + +For example, a query for three signals on one date across all counties can be +submitted anonymously, but a query for three signals on a period of four weeks +across all counties requires an API key. + +An API key is a pseudonymous access token that grants privileged access to the +Epidata API. You can request an API key by registering with us. Privileges of +registration may include: + +1. restricted-access datasets +1. no rate limit +1. no limit on multiple selections + +We require an email address for all registrations so that we can contact you to +resolve problems with excessive or abnormal usage patterns. Any additional +personal information you provide to us at registration will be much appreciated, +because it will help us understand what our data is used for and inform our +plans and priorities, but is voluntary. + +You may also choose to share personal information with us to participate in user +surveys. + +We log information about API traffic including the query parameters, API key, +and source IP address for each request. We retain these logs for a period of not +longer than five years. We use this information for the following +purposes: + +* to monitor the responsiveness of the API service +* to monitor the relative popularity of different data and features, alone and + in concert with user survey results +* to identify excessive or abnormal usage patterns which may harm our system + +The logs are only available to members of our operations team, and are expunged +at or before they reach five years in age. + +If you provide us with your email address, we will only use it to contact you in +the following scenarios: + +* you asked a question in a user survey and we have an answer for you +* we make improvements or other changes to the Epidata API service +* the API service experiences an outage +* your API key is about to expire +* your API usage becomes excessive or abnormal +* a voluntary survey of our users, but no more than once every 6 months + +We store the mapping from tokens to email addresses in a location separate from +server logs, using security measures consistent with our internal information +security practices to help us keep your information secure. We only retrieve +this mapping to resolve cases of excessive or abnormal usage. We automatically +disassociate an email address from its API key when the API key has not been +used for six months, or upon user request. You can request that your +email address be removed from our records by filling out a +[deletion request](https://forms.gle/GucFmZHTMgEFjH197). + +For more information, see Carnegie Mellon’s privacy notice at +https://www.cmu.edu/legal/privacy-notice.html . Further questions can be +directed to delphi-support+privacy@andrew.cmu.edu. \ No newline at end of file diff --git a/docs/epidata_development.md b/docs/epidata_development.md index a2f0b7e8e..29a0fdde7 100644 --- a/docs/epidata_development.md +++ b/docs/epidata_development.md @@ -1,6 +1,6 @@ --- title: Epidata API Development Guide -nav_order: 3 +nav_order: 4 --- # Epidata API Development Guide diff --git a/docs/index.md b/docs/index.md index c49e97467..0ffb66b97 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,25 @@ group](https://delphi.cmu.edu/). The Epidata API includes: quick access to COVID data are available. - [Data about other diseases](api/README.md), including influenza, dengue, and other diseases tracked by Delphi through various data streams. + +Anyone may access the Epidata API anonymously without providing any personal +data. Anonymous API access is currently rate-limited and restricted to public +datasets with a maximum of two of the requested parameters having multiple +selections (signals, dates, versions, regions, etc). + +To request access to restricted datasets, no rate limit, and unlimited multiple +selections, you can [request a registered API key](https://forms.gle/hkBr5SfQgxguAfEt7). + +If you regularly or frequently use our system, please consider using an API key +even if your usage falls within the anonymous usage limits. API key usage helps +us understand who and how others are using our Delphi Epidata API, which may in +turn inform our future research, data partnerships, and funding. + +For more information about how we use the data you provide us through your +registration and API request activity, see our [Privacy +Statement](api/privacy_statement.md). At any time, you may submit a [Deletion +Request](https://forms.gle/GucFmZHTMgEFjH197) to have us deactivate your key and destroy all +information associating that key with your identity. The Delphi group is extremely grateful to Pedrito Maynard-Zhang for all his help with the Epidata API [documentation](api/README.md). diff --git a/docs/new_endpoint_tutorial.md b/docs/new_endpoint_tutorial.md index 436b89908..d4deed6d4 100644 --- a/docs/new_endpoint_tutorial.md +++ b/docs/new_endpoint_tutorial.md @@ -1,6 +1,6 @@ --- title: New Endpoint Tutorial -nav_order: 4 +nav_order: 5 --- # Tutorial: Adding a new API endpoint diff --git a/docs/symptom-survey/index.md b/docs/symptom-survey/index.md index ac1ba9ac7..ec926dea3 100644 --- a/docs/symptom-survey/index.md +++ b/docs/symptom-survey/index.md @@ -1,7 +1,7 @@ --- title: COVID-19 Trends and Impact Survey has_children: true -nav_order: 5 +nav_order: 6 --- # COVID-19 Trends and Impact Survey From 406f1f8b79679478606616dbeba25d253a87d55d Mon Sep 17 00:00:00 2001 From: Kathryn Mazaitis Date: Tue, 2 May 2023 17:09:46 -0400 Subject: [PATCH 2/4] Moved access policy from privacy page to api key overview page --- docs/api/api_keys.md | 37 +++++++++++++++++++++++++++++++---- docs/api/privacy_statement.md | 27 ++++++------------------- 2 files changed, 39 insertions(+), 25 deletions(-) diff --git a/docs/api/api_keys.md b/docs/api/api_keys.md index c6744f441..6dc133709 100644 --- a/docs/api/api_keys.md +++ b/docs/api/api_keys.md @@ -7,17 +7,46 @@ has_children: true # Epidata API Keys Anyone may access the Epidata API anonymously without providing any personal -data. If you choose to [register for an API key](https://forms.gle/hkBr5SfQgxguAfEt7), +data. Anonymous API access is subject to the following restrictions: + +1. public datasets only +1. rate-limited to $RATE_LIMIT +1. only two parameters may have multiple selections + +For example, a query for three signals on one date across all counties can be +submitted anonymously, but a query for three signals on a period of four weeks +across all counties requires an API key. + +An API key is a pseudonymous access token that grants privileged access to the +Epidata API. You can request an API key by +[registering with us](https://forms.gle/hkBr5SfQgxguAfEt7). +Privileges of registration may include: + +1. restricted-access datasets +1. no rate limit +1. no limit on multiple selections + +We require an email address for all registrations so that we can contact you to +resolve problems with excessive or abnormal usage patterns. Any additional +personal information you provide to us at registration will be much appreciated, +because it will help us understand what our data is used for and inform our +plans and priorities, but is voluntary. For more information on how we use and +store the information you provide us at registration time, see our +[privacy statement](api/privacy_statement.md). + +## Usage + +If you choose to [register for an API key](https://forms.gle/hkBr5SfQgxguAfEt7), there are several ways to use your key to authenticate your requests: -## Via request parameter +### Via request parameter The request parameter “api_key” can be used to pass the API key to the server. Example: http://delphi.cmu.edu/epidata/covidcast/meta?api_key=your_api_key_here -## Via Basic Authentication +### Via Basic Authentication Another method is using the HTTP basic authorization header with the username "epidata" and the API key as the password. Example: @@ -26,7 +55,7 @@ Another method is using the HTTP basic authorization header with the username curl -u 'epidata:your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta ``` -## Via Bearer Token +### Via Bearer Token Another method is providing the key in a bearer token header. Example: diff --git a/docs/api/privacy_statement.md b/docs/api/privacy_statement.md index e3b08352e..002367931 100644 --- a/docs/api/privacy_statement.md +++ b/docs/api/privacy_statement.md @@ -6,25 +6,10 @@ parent: API Keys # Delphi Privacy Statement Anyone may access the Epidata API anonymously without providing any personal -data. Anonymous API access is subject to the following restrictions: +data. -1. public datasets only -1. rate-limited to $RATE_LIMIT -1. only two parameters may have multiple selections - -For example, a query for three signals on one date across all counties can be -submitted anonymously, but a query for three signals on a period of four weeks -across all counties requires an API key. - -An API key is a pseudonymous access token that grants privileged access to the -Epidata API. You can request an API key by registering with us. Privileges of -registration may include: - -1. restricted-access datasets -1. no rate limit -1. no limit on multiple selections - -We require an email address for all registrations so that we can contact you to +Some features of the API are only available by registering for an API key. We +require an email address for all registrations so that we can contact you to resolve problems with excessive or abnormal usage patterns. Any additional personal information you provide to us at registration will be much appreciated, because it will help us understand what our data is used for and inform our @@ -65,6 +50,6 @@ used for six months, or upon user request. You can request that your email address be removed from our records by filling out a [deletion request](https://forms.gle/GucFmZHTMgEFjH197). -For more information, see Carnegie Mellon’s privacy notice at -https://www.cmu.edu/legal/privacy-notice.html . Further questions can be -directed to delphi-support+privacy@andrew.cmu.edu. \ No newline at end of file +For more information, see +[Carnegie Mellon’s privacy notice](https://www.cmu.edu/legal/privacy-notice.html). +Further questions can be directed to delphi-support+privacy@andrew.cmu.edu. \ No newline at end of file From 2a9d672cefa07cc2961c16b4d6f1dbeb322c7f01 Mon Sep 17 00:00:00 2001 From: Katie Mazaitis Date: Mon, 8 May 2023 16:57:20 -0400 Subject: [PATCH 3/4] Update rate limit and fix link formatting --- docs/api/api_keys.md | 2 +- docs/index.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/api_keys.md b/docs/api/api_keys.md index 6dc133709..948929830 100644 --- a/docs/api/api_keys.md +++ b/docs/api/api_keys.md @@ -10,7 +10,7 @@ Anyone may access the Epidata API anonymously without providing any personal data. Anonymous API access is subject to the following restrictions: 1. public datasets only -1. rate-limited to $RATE_LIMIT +1. rate-limited to 100 requests per hour 1. only two parameters may have multiple selections For example, a query for three signals on one date across all counties can be diff --git a/docs/index.md b/docs/index.md index 0ffb66b97..8dacc6906 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,9 +29,9 @@ us understand who and how others are using our Delphi Epidata API, which may in turn inform our future research, data partnerships, and funding. For more information about how we use the data you provide us through your -registration and API request activity, see our [Privacy -Statement](api/privacy_statement.md). At any time, you may submit a [Deletion -Request](https://forms.gle/GucFmZHTMgEFjH197) to have us deactivate your key and destroy all +registration and API request activity, see our +[Privacy Statement](api/privacy_statement.md). At any time, you may submit a +[Deletion Request](https://forms.gle/GucFmZHTMgEFjH197) to have us deactivate your key and destroy all information associating that key with your identity. The Delphi group is extremely grateful to Pedrito Maynard-Zhang for all his From ad97ec198150aed9bbc266be536f8ab0753055a5 Mon Sep 17 00:00:00 2001 From: Katie Mazaitis Date: Tue, 9 May 2023 15:52:05 -0400 Subject: [PATCH 4/4] Use 0-indexed nav order --- docs/api/api_keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/api_keys.md b/docs/api/api_keys.md index 948929830..421135023 100644 --- a/docs/api/api_keys.md +++ b/docs/api/api_keys.md @@ -1,6 +1,6 @@ --- title: API Keys -nav_order: 2 +nav_order: 1 has_children: true ---