Skip to content

Commit 4fe0afb

Browse files
committed
docs: Update introduction text
1 parent 243ae6e commit 4fe0afb

1 file changed

Lines changed: 25 additions & 17 deletions

File tree

src/about/introduction.rst

Lines changed: 25 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,32 +5,41 @@ What is this?
55
*************
66

77
This is an open online book containing short scholarly API code examples (i.e., "recipes")
8-
that demonstrate how to work with various scholarly web service APIs. It is part of the University of
9-
Alabama Libraries efforts to support `Research Data Services`_.
8+
that demonstrate how to work with various scholarly web service APIs. It is part of the
9+
University of Alabama Libraries efforts to support `Research Data Services`_.
1010

1111
.. _Research Data Services: https://guides.lib.ua.edu/ResearchDataServices
1212

1313
What should I be aware of before getting started?
1414
*************************************************
1515

16-
Before interacting with any scholarly APIs (or similar web service), it is very important to review the
17-
usage policies, which generally includes information such as query limits and data reuse policies.
18-
We have endeavored to follow all appropriate API usage policies in our examples and have linked
19-
to the specific API policies where possible. While some APIs are openly accessible and do
20-
not require special authentication, other scholarly APIs require that you are affiliated with a
21-
subscribing institution, and have registered for an API key to use for authentication in API queries.
22-
We have added instructions about any necessary authentication within the relevant code recipes.
16+
.. important::
2317

18+
Before interacting with any scholarly APIs (or similar web services), it is important to
19+
review the provider's usage policies. These typically outline information such as query
20+
limits, permitted use-cases, and restrictions on data reuse. In this Cookbook, we have
21+
endeavored to follow all relevant API usage policies and have linked to the specific policy
22+
pages whenever possible.
2423

25-
.. important::
24+
While some APIs are accessible without special authentication, others require that you are
25+
affiliated with a subscribing institution and have registered for an API key. Any required
26+
authentication steps are noted within the individual code recipes.
27+
28+
For APIs associated with subscription-licensed resources, please contact your affiliated
29+
institution before getting started. Library or other staff can confirm whether API access is
30+
included in your institution's subscriptions and provide guidance on setup and use.
31+
32+
Remember that each database or publisher maintains its own terms for downstream use-cases
33+
such as text and data mining. If you have questions about these policies or appropriate use,
34+
contact your institution for assistance.
2635

2736
In general, scholarly APIs are designed for the collection of small to medium
2837
sized datasets; that is, in the range of 100s or maybe a few thousand queries at most
29-
(various with API). If you need large bulk datasets, an API is likely not the method to use, and
30-
there may be bulk data downloads available from the database instead.
38+
(various with API). If you need large bulk datasets, an API is likely not the method to use,
39+
and there may be bulk data downloads available from the database instead.
3140

32-
If you decide that your use-case is appropriate for a scholarly API (or similar web service), here are a few good general practices
33-
to follow when working with any web API:
41+
If you decide that your use-case is appropriate for a scholarly API (or similar web service),
42+
here are a few good general practices to follow when working with any web API:
3443

3544
1. Read the API documentation and usage guidelines before starting.
3645
2. Start with testing the behavior of the API using a single programmatic API request (i.e., not in a loop).
@@ -56,8 +65,7 @@ UA Libraries Scout database for programming books (e.g., `TI python`).
5665
UA Libraries Workshop lessons and references therein for more general
5766
programming content [#ua_work]_.
5867

59-
60-
Which Programming Languages are Covered?
68+
What programming languages are covered?
6169
****************************************
6270

6371
Currently, we have scholarly API code examples in Python and R (and a Z39.50 tutorial in Bash).
@@ -77,7 +85,7 @@ For good luck, let's add ``Hello World!`` in each programming language:
7785
7886
> print("Hello World!")
7987
80-
Who is Creating the Content?
88+
Who is creating the content?
8189
****************************
8290

8391
The Scholarly API Cookbook content is authored by University of Alabama

0 commit comments

Comments
 (0)