How-To: Interact with the Radius API in Postman

This guide will show you how to use Postman to interact with the Radius API. Postman is a popular tool for interacting with REST APIs, and it can be used to explore the Radius API without writing any code.

Prerequisites

Before you get started, you’ll need to make sure you have the following tools and resources:

• Postman
• kubectl
• Radius environment

Step 1: Create Kubernetes objects

Radius uses the Kubernetes API aggregation layer to expose its API, so while Radius is not a Kubernetes operator itself, it leverages the Kubernetes platform to expose its own API.

To access the Radius API, begin by creating the necessary Kubernetes objects.

1. Create a new file named postman.yaml and add the following contents:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: postman-account
     namespace: radius-system
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: postman-role
     namespace: radius-system
   rules:
     - apiGroups: ["", "api.ucp.dev"]
       resources: ["*"]
       verbs: ["*"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: postman-role-binding
     namespace: radius-system
   subjects:
     - kind: ServiceAccount
       name: postman-account
       namespace: radius-system
   roleRef:
     kind: ClusterRole
     name: postman-role
     apiGroup: rbac.authorization.k8s.io
   

2. Save the file and then apply it using the following command:

   kubectl apply -f postman.yaml
   

   This will create a ServiceAccount named postman-account, a ClusterRole named postman-role with full access to all api.ucp.dev resources, and a ClusterRoleBinding named postman-role-binding that binds the postman-account to the postman-role.

Step 2: Generate a token

Now that you have created the necessary Kubernetes objects, you can generate a token that can be used to authenticate to the Kubernetes API.

1. Run the following command to generate a token for the postman-account service account:

   kubectl create token postman-account -n radius-system
   

   This will create a token with the default expiration time of 1 hour. If you want to set a different expiration time, you can use the --duration flag to specify a duration in seconds (up to 48 hours).

Step 3: Use Postman

Next, you’ll need to get the control plane API endpoint and use Postman to interact with the Radius API.

1. Begin by getting your cluster endpoint:

   kubectl cluster-info
   

   This will output information about your Kubernetes cluster, including the control plane API endpoint:

   Kubernetes control plane is running at https://kubernetes.docker.internal:6443
   CoreDNS is running at https://kubernetes.docker.internal:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
   

2. Open Postman and create a new request

3. Set the method to GET

4. Set the URL to the following, which will retrieve all your resource groups:

   <your-cluster-control-plane>/apis/api.ucp.dev/v1alpha3/planes/radius/local/resourcegroups?api-version=2023-10-01-preview
   

   

5. Open the Authorization tab and select Bearer Token from the Type dropdown. Paste the token you generated in step 2 into the Token field:

   

6. Click the Send button to send the request. You will now see your resource groups:

   {
       "value": [
           {
               "id": "/planes/radius/local/resourcegroups/default",
               "location": "global",
               "name": "default",
               "tags": {},
               "type": "System.Resources/resourceGroups"
           }
       ]
   }
   

7. Update your request URL to list all the Radius Environments in your resource group (make sure to update the name of your resource group in the URL. In this example the resource group name is default):

   <your-cluster-control-plane>/apis/api.ucp.dev/v1alpha3/planes/radius/local/resourcegroups/default/providers/Applications.Core/environments?api-version=2023-10-01-preview
   

   You should now see your Radius Environment(s):

   {
       "value": [
           {
               "id": "/planes/radius/local/resourcegroups/default/providers/Applications.Core/environments/default",
               "location": "global",
               "name": "default",
               "properties": {
                   "compute": {
                       "kind": "kubernetes",
                       "namespace": "default"
                   },
                   "provisioningState": "Succeeded",
                   "recipes": {...},
               },
               "systemData": {...},
               "tags": {},
               "type": "Applications.Core/environments"
           }
       ]
   }
   

Next step: Explore the Radius API

Now that you have successfully authenticated to the Radius API and interacted with resources, you can explore the API using the Radius API reference.