From 5a5260f8b447e353eb308a259d78b55de733b238 Mon Sep 17 00:00:00 2001 From: Bryan Fair Date: Mon, 21 Sep 2026 13:35:02 -0600 Subject: [PATCH 1/2] Update prototype endpoint documentation Add authentication messaging where needed. --- docs/content/endpoints/prototype-datasets.md | 21 +++++++++++++++++++- packages/docs-app-swagger/src/swagger.json | 2 -- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/content/endpoints/prototype-datasets.md b/docs/content/endpoints/prototype-datasets.md index 35acf7c..e9be896 100644 --- a/docs/content/endpoints/prototype-datasets.md +++ b/docs/content/endpoints/prototype-datasets.md @@ -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. @@ -82,6 +87,13 @@ Get information about a prototype dataset ### 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 @@ -121,6 +133,13 @@ Get information about data files for the prototype dataset ### 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 @@ -324,7 +343,7 @@ Type definition for a prototype dataset related data product |**dataProductDescription** |A brief description of the data product|string| -### **error** +### **error** Information about errors in the response diff --git a/packages/docs-app-swagger/src/swagger.json b/packages/docs-app-swagger/src/swagger.json index 18f26b2..77506c7 100644 --- a/packages/docs-app-swagger/src/swagger.json +++ b/packages/docs-app-swagger/src/swagger.json @@ -1859,7 +1859,6 @@ }, "/prototype/data/{uuid}": { "get": { - "security": [], "description": "Get information about data files for the prototype dataset", "tags": [ "Prototype Datasets" @@ -1906,7 +1905,6 @@ }, "/prototype/data/{uuid}/{filename}": { "get": { - "security": [], "description": "Gets a data file", "tags": [ "Prototype Datasets" From 5693f6b50ca69bebcbfd2c895abcc79b8929759f Mon Sep 17 00:00:00 2001 From: Bryan Fair Date: Tue, 22 Sep 2026 10:25:56 -0600 Subject: [PATCH 2/2] Add prototype endpoint url to auth areas --- docs/content/authentication.md | 35 +++++++++++++++++----------------- docs/content/index.md | 19 +++++++++--------- 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/content/authentication.md b/docs/content/authentication.md index 12a2592..9003d3f 100644 --- a/docs/content/authentication.md +++ b/docs/content/authentication.md @@ -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). -## **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" @@ -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" @@ -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 \ @@ -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) diff --git a/docs/content/index.md b/docs/content/index.md index 5c2e8b3..e6ac0ca 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,13 +1,14 @@ # 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) @@ -15,24 +16,24 @@ You do not need to authenticate in order to explore information about NEON data 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).