Skip to content

Latest commit

 

History

History
150 lines (101 loc) · 4.71 KB

api-basics.adoc

File metadata and controls

150 lines (101 loc) · 4.71 KB
sidebar permalink summary
sidebar
api-basics.html
The basics of using the NKS API, including creating an API token and how to validate requests.

Getting Started

Welcome to the NetApp Kubernetes Service (NKS) API Reference. This section guides you through the setup process of creating an NKS API token, passing the token in your API requests, and the response codes returned by the API.

To use the NKS API, you will need an NKS account. If you don’t have one already, you can sign up for a free 30-day trial with no credit card required at https://nks.netapp.io.

Resource URL

The full resource URL for the NKS API is https://api.nks.netapp.io.

Note
 For security reasons, this URL will return a "Resource not found" error in a browser.

The resource URL is meant to be used in a Curl or automated API request. For more information on using Curl, we recommend the official Curl documentation.

Authorization Requirements

All API requests must be authenticated with your API token. To obtain a token:

  1. Register or log in at NKS.

  2. Click your profile avatar in the top right corner and select Edit Profile.

  3. In the API Tokens section, click Add Token.

  4. Copy the token and save it somewhere safe. This is your only chance to view your API token. The token cannot be displayed after you leave or reload the page.

Access Rights

Your UI access and your API access are both tied to the same account. This means that you can only do through the API what you would be able to do through the UI.

Most API operations are scoped under the organization. You will only be able to carry out these operations if you have Owner level access to the specified organization.

Scope

The following resources are scoped under the organization:

  • Workspaces

  • Teams

  • Members

  • Keysets

  • Clusters

  • Nodes

  • Node Pools

  • Federations

  • Istio Mesh

  • Trusted Charts

  • Subscription

  • Invoices

  • Notifications

The user resource is scoped under the user account.

Usage

curl -X GET \
-H "Authorization: Bearer abcdef123456789abcdev123456789" \
"https://api.nks.netapp.io/orgs"

To authenticate, you must pass the API token as a Bearer token in the Authorization header for all API requests.

To do this, add -H "Authorization: Bearer {your API token}" to the request, as demonstrated in the example on the right.

Organization Number

After you create an API token, the page displays the example code to use it. This code includes your current organization ID, which is a critical component in your future API requests.

Note: You can also fetch your current organization ID from the Organizations resource.

In this example, the user’s organization ID is 381:

API token example code

Example

curl -X GET \
-H "Authorization: Bearer {API token}" \
"https://api.nks.netapp.io/orgs/{Org ID}/clusters"

This query returns a list of your current active clusters within the selected organization.

For example:

curl -X GET \
-H "Authorization: Bearer abcdef123456789abcdev123456789" \
"https://api.nks.netapp.io/orgs/381/clusters"

Response Codes

Example using the -i flag to view all headers:

curl -i -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer abcdef123456789abcdev123456789" \
-d @updateorg.json "https://api.nks.netapp.io/orgs/381"

This query will trigger a 400 error. Using the -i flag returns the additional response:

{"detail":"JSON parse error - Expecting property name enclosed in double quotes: line 1 column 72 (char 71)"}

The NKS API uses the following response codes:

Response Description

200

OK: The request succeeded.

400

Bad Request: The data sent with the request is not valid. For more details, use the -i flag in your request to view all headers. This returns additional information about the cause of the error.

401

Unauthorized: "Authentication credentials were not provided." You did not provide an API key, or the provided API key is invalid.

403

Forbidden: You are not allowed to access this endpoint or resource.

404

Not Found: The endpoint or resource was not found.

405

Method Not Allowed: The endpoint does not allow this method.

500

Internal Server Error: We had a problem with our server. Try again later.

503

Service Unavailable: We are temporarily offline or experiencing an outage. If this error persists, please contact our support department.

Did these articles answer your question? If not, contact us.