From 105d1c839e99730c04363baf9da50fd2eab6bc6c Mon Sep 17 00:00:00 2001 From: Fi Quick <47183728+fiquick@users.noreply.github.com> Date: Mon, 3 Mar 2025 14:58:58 +0000 Subject: [PATCH 1/2] add api to content nav --- modules/ROOT/content-nav.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 0db201c1c..3aef15fb9 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -102,6 +102,11 @@ Generic Start * Connecting applications ** xref:connecting-applications/overview.adoc[Drivers and libraries] + +* Aura API +** xref:platform/api/overview.adoc[] +** xref:platform/api/authentication.adoc[] +** link:{neo4j-docs-base-uri}/aura/platform/api/specification/[API Specification] //// AuraDB End //// From b99c084d8491a4e901efd0b16dfc7e29da1a27be Mon Sep 17 00:00:00 2001 From: Fi Quick <47183728+fiquick@users.noreply.github.com> Date: Mon, 3 Mar 2025 15:51:11 +0000 Subject: [PATCH 2/2] add latest info --- .../pages/platform/api/authentication.adoc | 33 +++++++++++++------ modules/ROOT/pages/platform/api/overview.adoc | 17 ++++++---- 2 files changed, 34 insertions(+), 16 deletions(-) diff --git a/modules/ROOT/pages/platform/api/authentication.adoc b/modules/ROOT/pages/platform/api/authentication.adoc index 80c852ca2..e79028365 100644 --- a/modules/ROOT/pages/platform/api/authentication.adoc +++ b/modules/ROOT/pages/platform/api/authentication.adoc @@ -6,13 +6,14 @@ The Aura API uses OAuth 2.0 for API authentication. == Creating credentials -[NOTE] -==== -Enterprise users have unrestricted access to creating API credentials. +AuraDB Virtual Dedicated Cloud users, and AuraDS Enterprise users have unrestricted access to creating API credentials. However, users with Free and Professional instances must have entered billing information or be a member of a marketplace project before they can create API credentials. -==== +API credentials are linked to the user account, inheriting its capabilities and roles. +The API credentials never expire unless you delete them. -. Navigate to the https://console.neo4j.io/#account[Neo4j Aura console Account Details page] in your browser. +To create credentials: + +. Navigate to the https://console.neo4j.io/#account[Neo4j Aura Console Account Details page] in your browser. . Select the *Create* button in the *Aura API Credentials* section. . Enter a *Client name*, and select *Create*. . Securely save the *Client ID* and *Client Secret* you are given in the resulting modal; you will need these for the next step. @@ -63,7 +64,7 @@ Authentication to the token endpoint uses HTTP Basic Authentication, where the c |=== |Parameter |Value -|grant_type +|`grant_type` |`client_credentials` |=== @@ -112,7 +113,7 @@ response = requests.request( print(response.json()) ---- -<1> `client_id` and `client_secret` must be set to the values obtained from the Aura console. +<1> `client_id` and `client_secret` must be set to the values obtained from the Aura Console. ===== ==== @@ -123,12 +124,14 @@ print(response.json()) ---- { "access_token": "", <1> - "expires_in": 3600, + "expires_in": 3600, <2> "token_type": "bearer" } ---- <1> The `access_token` returned here is what you will provide as the Bearer Token in the `Authorization` header of Aura API requests. +<2> The value of `expires_in` is the token expiration time in seconds. +Once the token expires, the application must request a new one. ==== HTTP response codes @@ -157,7 +160,17 @@ print(response.json()) |The request body is missing. |=== +=== Excessive token requests + +Excessive token requests may cause inefficiencies or rate-limiting. +You can optimize your API usage by following these steps: + +* *Retrieve the token once per hour:* As tokens remain valid for an hour, reduce the frequency of token requests and reuse the same token for multiple API calls. + +* *Implement token caching:* Store the token securely within your system to reuse it for subsequent requests during its validity period, minimizing unnecessary calls to the endpoint. + === Token expiration -If you attempt to send a request to the Aura API, authenticated using an expired access token, you will receive a 403 Forbidden response. -You will need to obtain a new token to continue using the API. +Access tokens are temporary and expire after one hour. +If you send a request to the Aura API using an expired token, you will receive a `403 Forbidden` response. +To continue using the API, you must obtain a new token using the Aura API credentials. diff --git a/modules/ROOT/pages/platform/api/overview.adoc b/modules/ROOT/pages/platform/api/overview.adoc index 9a75e6f43..0104ea95c 100644 --- a/modules/ROOT/pages/platform/api/overview.adoc +++ b/modules/ROOT/pages/platform/api/overview.adoc @@ -2,7 +2,10 @@ = Overview :description: This page introduces the Aura API. -The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the console. +label:AuraDB-Virtual-Dedicated-Cloud[] +label:AuraDS-Enterprise[] + +The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the Console. A complete list of the available endpoints can be seen and tested in the link:{neo4j-docs-base-uri}/aura/platform/api/specification/[API Specification]. @@ -34,13 +37,15 @@ The following example shows how to use the base URL and versioning to make a req == Retries -In the event of `5xx` server error responses, you may consider retrying the request after a delay if it is safe to do so. The response may include a `Retry-After` header with a suggestion of a suitable minimum delay before attempting to retry. +In the event of `5xx` server error responses, you may consider retrying the request after a delay if it is safe to do so. +The response may include a `Retry-After` header with a suggestion of a suitable minimum delay before attempting to retry. -Rate limiting is set to 125 requests per minute. +The global rate limit for all requests is 125 requests per minute. -You should consider your use of the Rate Limit before attempting to retry, and we recommend using an exponential backoff delay with a limited number of retries before giving up. +You should consider your use of the rate limit before attempting to retry, and it is recommended that you use an exponential backoff delay with a limited number of retries before giving up. -A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as `GET`. If for example, you attempt to retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result. +A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as `GET`. +If, for example, you retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result. In the case of `429 Too Many Requests`, we would recommend slowing down the rate of all requests sent from your client application and consider retrying with a suitable minimum delay and backoff strategy. @@ -52,4 +57,4 @@ An `X-Request-Id` response header is returned with each request and can be used The value of this header contains a unique ID that can be used to track the journey of a request. -If you run into any issues with a particular request, you can https://support.neo4j.com/[raise a support ticket] and provide the `X-Request-Id`. +If you run into any issues with a particular request, you can https://support.neo4j.com/[raise a support ticket] and provide the `X-Request-Id`. \ No newline at end of file