Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 18 additions & 17 deletions docs/content/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,34 @@
You do not need to authenticate in order to explore information about NEON data or locations. However, if you will be using the APIs to download data products or sample data, or using the APIs intensively, then you will need to sign up for and use an [API Token](#api-tokens). To learn more about setting up and utilizing an API Token, see [API Token Setup](https://www.neonscience.org/resources/learning-hub/tutorials/api-token-setup).

<a name="api-tokens"></a>
## **API Tokens**
## **API Tokens**

The NEON data API provides users the ability to manage and obtain API tokens.

### **Generation**

In order to generate an API Token, you must first sign in with your account
or create an account with the Data Portal. You can sign up or sign in by accessing
the [My Account](https://data.neonscience.org/myaccount) page. Once authenticated
and verified, you can request a token using the API Token management section
In order to generate an API Token, you must first sign in with your account
or create an account with the Data Portal. You can sign up or sign in by accessing
the [My Account](https://data.neonscience.org/myaccount) page. Once authenticated
and verified, you can request a token using the API Token management section
provided on the account page.

!!! warning
Tokens should be treated like credentials.
Never share your API token and store it in a secure location.
It is strongly recommended to never commit this token to source control
repositories such as GitHub. If your token has been compromised,
please disable or delete the token through the
[My Account](https://data.neonscience.org/myaccount) page and discontinue
Tokens should be treated like credentials.
Never share your API token and store it in a secure location.
It is strongly recommended to never commit this token to source control
repositories such as GitHub. If your token has been compromised,
please disable or delete the token through the
[My Account](https://data.neonscience.org/myaccount) page and discontinue
use of the token.

### **Utilization**

To utilize an API Token when making a request, include it as a header or query
parameter:
To utilize an API Token when making a request, include it as a header or query
parameter:

- Header Name: `X-API-Token`
- Query Parameter Name: `apiToken`
- Query Parameter Name: `apiToken`

=== "cURL"

Expand All @@ -40,13 +40,13 @@ parameter:
curl --verbose -H "X-API-Token: TOKEN_VALUE" \
-X GET https://data.neonscience.org/api/v0/products/DP1.00001.001 \
>> neon-data-products-DP1.00001.001.json
```
```
``` bash
# apiToken query parameter
curl --verbose \
-X GET https://data.neonscience.org/api/v0/products/DP1.00001.001?apiToken=TOKEN_VALUE \
>> neon-data-products-DP1.00001.001.json
```
```

=== "HTTPie"

Expand All @@ -56,7 +56,7 @@ parameter:
http --download --output=neon-data-products-DP1.00001.001.json \
GET https://data.neonscience.org/api/v0/products/DP1.00001.001 \
X-API-Token:TOKEN_VALUE
```
```
``` bash
# apiToken query parameter
http --download --output=neon-data-products-DP1.00001.001.json \
Expand All @@ -69,6 +69,7 @@ Endpoints that require authentication are identified in the documentation for ea

- [Data Endpoints](/data-api/endpoints/data)
- [Data Query Endpoints](/data-api/endpoints/data-query)
- [Prototype Datasets Endpoints](/data-api/endpoints/prototype-datasets)
- [Releases Endpoints](/data-api/endpoints/releases)
- [Samples Endpoints](/data-api/endpoints/samples)

Expand Down
21 changes: 20 additions & 1 deletion docs/content/endpoints/prototype-datasets.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Prototype Datasets Endpoint

!!! requires-auth "Requires Authentication"

One or more endpoints require [API Token](/data-api/authentication#api-tokens) authentication, indicated below.


The `/prototype/datasets` endpoint provides information about all prototype NEON datasets. Prototype datasets have generally been collected during the design and construction of NEON. These datasets are not necessarily representative of the long-term standardized data otherwise available on the NEON data portal. Prototype data are provided as downloadable zip files.

The `/prototype/data` endpoint provides access to all data associated with a single dataset.
Expand Down Expand Up @@ -82,6 +87,13 @@ Get information about a prototype dataset
<a name="get_prototype_data_uuid"></a>
### GET `/prototype/data/{uuid}`

#### **Authentication**

!!! requires-auth "Requires Authentication"

[API Token](/data-api/authentication#api-tokens) required to utilize this endpoint.


#### **Description**
Get information about data files for the prototype dataset

Expand Down Expand Up @@ -121,6 +133,13 @@ Get information about data files for the prototype dataset
<a name="get_prototype_data_uuid_file"></a>
### GET `/prototype/data/{uuid}/{filename}`

#### **Authentication**

!!! requires-auth "Requires Authentication"

[API Token](/data-api/authentication#api-tokens) required to utilize this endpoint.


#### **Description**
Gets a data file

Expand Down Expand Up @@ -324,7 +343,7 @@ Type definition for a prototype dataset related data product
|**dataProductDescription** |A brief description of the data product|string|

<a name="error"></a>
### **error**
### **error**

Information about errors in the response

Expand Down
19 changes: 10 additions & 9 deletions docs/content/index.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,39 @@
# NEON Data API

## **Introduction**
The NEON Data API (Application Programming Interface) can be used to quickly access data as well as information about NEON's data products, samples, and sampling locations. It provides a simple means of constructing URLs or cURL statements that return information in a common machine-readable format, [JSON (JavaScript Object Notation)](https://json.org/json-en.html).
The NEON Data API (Application Programming Interface) can be used to quickly access data as well as information about NEON's data products, samples, and sampling locations. It provides a simple means of constructing URLs or cURL statements that return information in a common machine-readable format, [JSON (JavaScript Object Notation)](https://json.org/json-en.html).

## **Authentication**
You do not need to authenticate in order to explore information about NEON data or locations. However, if you will be using the APIs to download data products or sample data, or using the APIs intensively, then you will need to sign up for and use an [API Token](/data-api/authentication#api-tokens). To learn more about setting up and utilizing an API Token, see [API Token Setup](https://www.neonscience.org/resources/learning-hub/tutorials/api-token-setup). Endpoints that require authentication are identified in the documentation for each endpoint:

- [Data Endpoints](/data-api/endpoints/data)
- [Data Query Endpoints](/data-api/endpoints/data-query)
- [Prototype Datasets Endpoints](/data-api/endpoints/prototype-datasets)
- [Releases Endpoints](/data-api/endpoints/releases)
- [Samples Endpoints](/data-api/endpoints/samples)

## **Data Use Policy and Licensing**
NEON data products and sample data are licensed under a Creative Commons Attribution 4.0 International License ([CC-BY](https://creativecommons.org/licenses/by/4.0/)). For more information, visit the [Data Guidelines and Policies](https://www.neonscience.org/data-samples/guidelines-policies) page.

## **R & Python packages**
The neonUtilities packages are the easiest way to download and reformat NEON data.
The neonUtilities packages are the easiest way to download and reformat NEON data.

* [`neonUtilities` R package](https://cran.r-project.org/web/packages/neonUtilities/index.html)
* [`neonutilities` Python package](https://pypi.org/project/neonutilities)
* Check out the ["Use the neonUtilities Package to Access NEON Data" tutorial](https://www.neonscience.org/resources/learning-hub/tutorials/neondatastackr)

* [`neonUtilities` R package](https://cran.r-project.org/web/packages/neonUtilities/index.html)
* [`neonutilities` Python package](https://pypi.org/project/neonutilities)
* Check out the ["Use the neonUtilities Package to Access NEON Data" tutorial](https://www.neonscience.org/resources/learning-hub/tutorials/neondatastackr)

## **REST API Explorer**
The API provides numerous endpoints, some of which provide the option to enter values for specific parameters that allow you to refine your search. To learn more about each endpoint, click on “REST API Endpoints” in the navigation menu. To try each endpoint out, open the [REST API Explorer](https://data.neonscience.org/data-api/explorer/).
The API provides numerous endpoints, some of which provide the option to enter values for specific parameters that allow you to refine your search. To learn more about each endpoint, click on “REST API Endpoints” in the navigation menu. To try each endpoint out, open the [REST API Explorer](https://data.neonscience.org/data-api/explorer/).

## **GraphQL**
The [GraphQL](https://data.neonscience.org/data-api/graphql/) endpoint allows users to take advantage of the flexibility and efficiency of the [GraphQL data query language](https://graphql.org/) to access NEON metadata. The `/graphql` endpoint affords users the ability to define and receive only desired metadata.

## **Other Resources**

* [The NEON Data API GitHub repository](https://github.com/NEONScience/neon-data-api),
* [The NEON Data API GitHub repository](https://github.com/NEONScience/neon-data-api),
* [Using the NEON API tutorial](https://www.neonscience.org/neon-api-usage)
* Download the [Swagger documentation](https://raw.githubusercontent.com/NEONScience/neon-data-api/refs/heads/main/packages/docs-app-swagger/src/swagger.json)

## **Provide Feedback**
If you have design ideas, functionality requests, bug notes, examples of how you used the API, etc., please [contact us](https://www.neonscience.org/about/contact-us).

Expand Down
2 changes: 0 additions & 2 deletions packages/docs-app-swagger/src/swagger.json
Original file line number Diff line number Diff line change
Expand Up @@ -1859,7 +1859,6 @@
},
"/prototype/data/{uuid}": {
"get": {
"security": [],
"description": "Get information about data files for the prototype dataset",
"tags": [
"Prototype Datasets"
Expand Down Expand Up @@ -1906,7 +1905,6 @@
},
"/prototype/data/{uuid}/{filename}": {
"get": {
"security": [],
"description": "Gets a data file",
"tags": [
"Prototype Datasets"
Expand Down