rest-api.md

RESTful APIs

Initialize the openPAIClient

import { PAIV2 } from '@microsoft/openpai-js-sdk';

const cluster: PAIV2.IPAICluster = {
    username: '<username>',
    password: '<password>',
    token: '<token>',
    rest_server_uri: '<The host>/rest-server'
};
const openPAIClient = new PAIV2.OpenPAIClient(cluster);

api info

token

• Get your currently signed tokens (GET /api/v2/tokens)

  tokens = await openPAIClient.auth.getTokens();

• Revoke a token (DELETE /api/v2/tokens/{token})

  await openPAIClient.auth.deleteToken(token);

• Create an application access token in the system (POST /api/v2/tokens/application)

  token = await openPAIClient.auth.createApplicationToken();

authn

• User login with Azure AD (GET /api/v2/authn/oidc/login)

  redirect = await openPAIClient.authn.oidcLogin();

• User logout from Azure AD (GET /api/v2/authn/oidc/logout)

  redirect = await openPAIClient.authn.oidcLogout();

• Get an access token using username and password (POST /api/v2/authn/basic/login)

  loginInfo = await openPAIClient.authn.login(username, password);

• Logout and revoke the token (DELETE /api/v2/authn/basic/logout)

  await openPAIClient.authn.logout();

user

• Create a user in the system (POST /api/v2/users/)

  await openPAIClient.user.createUser(user);
  await openPAIClient.user.createUser({username, password, admin, email, virtualClusters});

• Get all users in the system (GET /api/v2/users/)

  list = await openPAIClient.user.getAllUser();

• Update a user in the system (PUT /api/v2/users)

  await openPAIClient.user.updateVirtualcluster(user);
  await openPAIClient.user.updateVirtualcluster(user, patch);

• Update user's own profile (PUT /api/v2/users/me)

  await openPAIClient.user.updateUserSelf(user);
  await openPAIClient.user.updateUserSelf(user, patch);

• Get a user's data (GET /api/v2/users/{username})

  user = await openPAIClient.user.getUser(username);

• Remove a user in the system (DELETE /api/v2/users/{username})

  await openPAIClient.user.deleteUser(username);

• Add a group for user (PUT /api/v2/users/{username}/group/)

  await openPAIClient.user.updateUserGroup(username, groupname);

• Remove a group from user's grouplist (DELETE /api/v2/users/{username}/group)

  await openPAIClient.user.removeGroup(username, groupName);

• Replace user's grouplist (PUT /api/v2/users/{username}/grouplist/)

  await openPAIClient.user.updateUserGrouplist(username, grouplist);

group

• Get all group objects in the system (GET /api/v2/groups)

  groups = await openPAIClient.group.getAllGroup();

• Create a group in the system (POST /api/v2/groups)

  await openPAIClient.group.createGroup(group);

• Update a group in the system (PUT /api/v2/groups)

  await openPAIClient.group.updateGroup(group);

• Get a group in the system (GET /api/v2/groups/{groupname})

  group = await openPAIClient.group.getGroup(groupname);

• Delete a group in the system (DELETE /api/v2/groups/{groupname})

  await openPAIClient.group.deleteGroup(groupname);

• Get the user array of a group in the system (GET /api/v2/groups/{groupname}/userlist)

  users = await openPAIClient.group.getGroupMembers(groupname);

virtual cluster

• Get the list of virtual clusters (GET /api/v2/virtual-clusters)

  list = await openPAIClient.virtualCluster.listVirtualClusters();

• Get virtual cluster status in the system (GET /api/v2/virtual-clusters/{vcName})

  vc = await openPAIClient.virtualCluster.getVirtualCluster(vcName);

job

• Submit a job in the system (POST /api/v2/jobs)

  await openPAIClient.job.createJob(config);

• Get the list of jobs (GET /api/v2/jobs)

  list = await openPAIClient.job.listJobs();
  list = await openPAIClient.job.listJobs(username);

• Get job status (GET /api/v2/jobs/{username}~{jobname})

  job = await openPAIClient.job.getJob(username, jobname);

• Get job status with specific attempt(GET /api/v2/jobs/{username}~{jobname}/attempts/{jobAttemptId})

  job = await openPAIClient.job.getJob(username, jobname, jobAttemptId);

• Get job config (GET /api/v2/jobs/{username}~{jobname}/config)

  config = await openPAIClient.job.getJobConfig(username, jobname);

• Start or stop a job (PUT /api/v2/jobs/{username}~{jobname}/exectionType)

  await openPAIClient.job.updateJobExecutionType(username, jobname, 'START');
  await openPAIClient.job.updateJobExecutionType(username, jobname, 'STOP');

• Add a tag to a job (PUT /api/v2/jobs/{username}~{jobname}/tag)

  await openPAIClient.job.addTag(username, jobname, tag);

• Delete a tag from a job (DELETE /api/v2/jobs/{username}~{jobname}/tag)

  await openPAIClient.job.deleteTag(username, jobname, tag);

• Get task status (GET /api/v2/jobs/{username}~{jobname}/attempts/{jobAttemptId}/taskRoles/{taskRoleName}/taskIndex/{taskIndex}/attempts)

  await openPAIClient.job.getTask(username, jobname, jobAttemptId, taskRoleName, taskIndex);

job history

• Check if job attempts is healthy (GET /api/v2/jobs/{username}~{jobname}/job-attempts/healthz)

  response = await openPAIClient.job.getJobAttemptsHealthz(username, jobname);

• Get all attempts of a job (GET /api/v2/jobs/{user}~{job}/job-attempts)

  attempts = await openPAIClient.job.getJobAttempts(username, jobname);

• Get a specific attempt by attempt index (GET /api/v2/jobs/{user}~{job}/job-attempts/{attempt})

  attempt = await openPAIClient.job.getJobAttempt(username, jobname, index);

storage

• Get storage list (persistent volume claims) for current user (GET /api/v2/storages)

  storages = await openPAIClient.storage.getStorages();

• Get storage (persistent volume claim) for the given name (GET /api/v2/storages/{storagename})

  storage = await openPAIClient.storage.getStorage(storagename);

kubernetes

• Get kubernetes node list (GET /api/v2/kubernetes/nodes)

  nodes = await openPAIClient.kubernetes.getK8sNodes();

• Get kubernetes pod list (GET /api/v2/kubernetes/pods)

  pods = await openPAIClient.kubernetes.getK8sPods();