Skip to content

api-reference.md

Latest commit

 

History

History
261 lines (186 loc) · 7.04 KB

api-reference.md

File metadata and controls

261 lines (186 loc) · 7.04 KB
title REST API
description Browse the Layer5 Cloud REST API inside the docs, powered by the shared OpenAPI schema.
weight 1
categories
Reference
tags
extensibility
layout rest-apis
display_toc false
body_class rest-api-reference-page
hide_readingtime true

To create integrations, retrieve data, and automate your cloud native infrastructure, build with the Layer5 Cloud REST API.

Authenticating with the API

In order to authenticate to Layer5 Cloud's REST API, you need to generate and use a security token. Visit your user account's security tokens and generate a long-lived token. Security tokens remain valid until you revoke them, and you can issue as many as you need.

To authenticate with the API, pass the token as a bearer token in the Authorization header. For example, in cURL:

curl <protocol>://<Layer5-cloud-hostname>/api/identity/users/profile \
-H "Authorization: Bearer <token>"
  • Replace <protocol> with http or https depending on your Layer5 Cloud instance.
  • Replace <Layer5-cloud-hostname> with the hostname or IP address of your hosted Layer5 Cloud instance. For example, https://cloud.layer5.io.
  • Replace the path with the API endpoint you want to access.
  • Replace <token> with the security token you generated.

Specifying Organization Context

{{< alert type="info" title="API Tokens are User-Scoped" >}} Layer5 Cloud API tokens are scoped to your user account, not to a specific organization. This means a single API token provides access to all organizations you are a member of. For users who belong to multiple organizations, you need to explicitly specify which organization your API requests should operate on.

This is similar to how GitHub Personal Access Tokens work, where a single token grants access to all repositories and organizations the user has access to. {{< /alert >}}

There are two ways to control the organization context for your API requests:

Using the layer5-current-orgid Header

Include the layer5-current-orgid header with your organization's ID to specify the target organization for a request:

{{< tabpane >}} {{< tab header="cURL" >}} curl -X GET "https://cloud.layer5.io/api/environments"
-H "Authorization: Bearer "
-H "layer5-current-orgid: "

{{< /tab >}}

{{< tab header="JavaScript" >}}

const token = "Your-Token"; const orgId = "Your-Organization-ID";

async function listEnvironments() { const res = await fetch("https://cloud.layer5.io/api/environments", { method: "GET", headers: { Authorization: Bearer ${token}, "layer5-current-orgid": orgId, }, }); const data = await res.json(); console.log(data); }

listEnvironments();

{{< /tab >}}

{{< tab header="Python" >}}

import requests

url = "https://cloud.layer5.io/api/environments" headers = { "Authorization": "Bearer ", "layer5-current-orgid": "" }

res = requests.get(url, headers=headers) print(res.json())

{{< /tab >}}

{{< /tabpane >}}

Setting Organization and Workspace Preferences

Alternatively, you can set your default organization and workspace using the Preferences API. This sets your user preferences so that subsequent API requests will use the specified organization and workspace context:

{{< tabpane >}} {{< tab header="cURL" >}}

Set organization and workspace preferences

curl -X PUT "https://cloud.layer5.io/api/identity/users/preferences"
-H "Authorization: Bearer "
-H "Content-Type: application/json"
-d '{ "selectedOrganization": "", "selectedWorkspace": "" }'

{{< /tab >}}

{{< tab header="JavaScript" >}}

const token = "Your-Token";

async function setPreferences() { const res = await fetch("https://cloud.layer5.io/api/identity/users/preferences", { method: "PUT", headers: { Authorization: Bearer ${token}, "Content-Type": "application/json", }, body: JSON.stringify({ selectedOrganization: "", selectedWorkspace: "", }), }); const data = await res.json(); console.log(data); }

setPreferences();

{{< /tab >}}

{{< tab header="Python" >}}

import requests import json

url = "https://cloud.layer5.io/api/identity/users/preferences" headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } payload = { "selectedOrganization": "", "selectedWorkspace": "" }

res = requests.put(url, headers=headers, data=json.dumps(payload)) print(res.json())

{{< /tab >}}

{{< /tabpane >}}

API Example

The following example demonstrate how to retrieve information from the Academy REST APIs.

Get the total number of registered learners in Academy

Use the Layer5 Cloud API to retrieve the total number of registered learners. Pass your Security Token as a Bearer token in the Authorization header (as shown in Authenticating with API). The response JSON includes an array of user objects.

{{< tabpane >}} {{< tab header="cURL" >}} curl -s -X GET "https://cloud.layer5.io/api/academy/cirricula"
-H "Authorization: Bearer "
| jq '[.data[].registration_count] | add'

{{< /tab >}}

{{< tab header="JavaScript" >}}

const token = "Your-Token"

async function getTotalLearners() { const res = await fetch("https://cloud.layer5.io/api/academy/cirricula", { headers: { Authorization: Bearer ${token} }, }); const data = await res.json(); const total = data.data.reduce((sum, path) => sum + path.registration_count, 0); console.log(total); }

getTotalLearners();

{{< /tab >}}

{{< tab header="Python" >}}

import requests

url = "https://cloud.layer5.io/api/academy/cirricula" headers = {"Authorization": "Bearer "}

res = requests.get(url, headers=headers) data = res.json() total = sum(item["registration_count"] for item in data["data"]) print(total)

{{< /tab >}}

{{< tab header="Golang" >}}

package main

import ( "encoding/json" "fmt" "io" "net/http" )

type Path struct { RegistrationCount int json:"registration_count" }

type Response struct { Data []Path json:"data" }

func main() { url := "https://cloud.layer5.io/api/academy/cirricula"

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer <your-token>")

client := &http.Client{}
res, err := client.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

body, _ := io.ReadAll(res.Body)

var response Response
if err := json.Unmarshal(body, &response); err != nil {
	panic(err)
}

total := 0
for _, path := range response.Data {
	total += path.RegistrationCount
}

fmt.Println(total)

}

{{< /tab >}}

{{< /tabpane >}}

This returns the number of Total registered learners:

130

All API Endpoints