Compare Rest-server APIs with Docs

[yiyione]

Compare Rest-server APIs with Docs

Go through all rest-server APIs and the document in API.md, found some problems in the document.

Problems

No document APIs

• GET /api/v1/authn/info
• POST /api/v1/authn/basic/login
• GET /api/v2/group/:groupname
• GET /api/v2/group/:groupname/userlist
• PUT /api/v1/user/:userName/jobs/:jobName
• DELETE /api/v1/user/:userName/jobs/:jobName
• GET /api/v2/jobs
• GET /api/v2/jobs/:frameworkName
• PUT /api/v2/jobs/:frameworkName/executionType
• GET /api/v2/jobs/:frameworkName/ssh
• CALL /api/v2/user/:username/jobs
• GET /api/v1/user/:username
• GET /api/v2/user/:username
• GET /api/v2/user
• CALL /api/v2/virtual-clusters

Different with document

• GET /api/v1/authn/oidc/login
  Got html code instead of the redirect uri.

• GET /api/v1/authn/oidc/logout
  Got html code instead of the redirect uri.

• POST /api/v1/token
  Response contains item "hasGitHubPAT": true | false, don't have document.

• PUT /api/v2/group/:groupname/extension
  The message of succeeded in API.md was wrong.

• DELETE /api/v2/group/:groupname
  The Parameters in API.md wasn't needed.

• POST /api/v1/user/:userName/jobs
  The Response was different.

• PUT /api/v1/user/:userName/jobs/:jobName/executionType
  The Status in Response if succeeded was different.

• POST /api/v2/jobs
  The message in Response if succeeded was different.

• PUT /api/v2/user/:username/email
  The Parameters and Response if succeeded was wrong.

• PUT /api/v1/virtual-clusters/:vcName/status
  The message in Response if succeeded was different.

Doesn't work APIs

• GET /api/v2/jobs
• PUT /api/v2/jobs/:frameworkName/executionType
• GET /api/v2/jobs/:frameworkName/ssh
• GET /api/v2/virtual-clusters/:virtualClusterName/resourceUnits

Confusion

• Get a v2 job information.
  We have two v2 api for Get job:
  GET /api/v2/user/:userName/jobs/:jobName and GET /api/v2/jobs/:username~jobname,
  The response was different.

Authn

GET /api/v1/authn/info

Status: 200
{
    "authn_type": 'basic' | 'OIDC',
    "loginURI": '/api/v1/authn/oidc/login' | '/api/v1/authn/basic/login',
    "loginURIMethod": 'get' | 'port'
}

No document in API.md

GET /api/v1/authn/oidc/login

Return html code.

Referenced by webportal: \src\rest-server\src\routes\authn.js

GET /api/v1/authn/oidc/logout

Return html code.

Referenced by webportal: \src\rest-server\src\routes\authn.js

GET/POST /api/v1/authn/oidc/return

Return html code.

API Documents:

b. Azure AD - OIDC mode
I. Login - get AuthCode
HTTP GET the redirect URL of Azure AD for authentication:

http://restserver/api/v1/authn/oidc/login
II. Login - get token with AuthCode
HTTP POST the token from AAD (AccessToken, IDToken, RefreshToken) to get OpenPAI's access token. Web-browser will call this API automatically after the step I.

HTTP://restserver/api/v1/authn/oidc/return
III. Logout
HTTP GET the redirect URL of Azure AD to sign out the authentication:

http://restserver/api/v1/authn/oidc/login

POST /api/v1/authn/basic/login

Post body:

{
    "username": "<username>",
    "password": "<password>",
    "expiration": "<expiration time in seconds>"
}

Response:

Status: 200

{
    "user": "<username>",
    "token": "<token string>",
    "admin": true | false,
    "hasGitHubPAT": true | false
}

Same response with /api/v1/token

Referenced by webportal: \src\webportal\src\app\home\index\conn.js

No document in API.md

Group

GET /api/v2/group/:groupname

Get the group:

    {
        "groupname": "<group name>",
        "description": "",
        "externalName": "",
        "extension": {
            "groupType": "admin" | "vc",
            "acls": {
                "admin": true | false,
                "virtualClusters": []
            }
        }
    }

No document in API.md

GET /api/v2/group

Get the group list:

[
    {
        "groupname": "<group name>",
        "description": "",
        "externalName": "",
        "extension": {
            "groupType": "admin" | "vc",
            "acls": {
                "admin": true | false,
                "virtualClusters": []
            }
        }
    },
    ...
]

No document in API.md

PUT /api/v2/group/:groupname/extension

Response:

Status: 201

{
    "message": "update group extension data successfully."
}

The message is different in API.md.

PUT /api/v2/group/:groupname/extension/:attribute

Response:

Status: 201

{
    "message": "Update group extension data successfully."
}

Same with the document.

PUT /api/v2/group/:groupname/description

Response:

Status: 201

{
    "message": "update group description data successfully."
}

Same with the document.

DELETE /api/v2/group/:groupname

Response:

Status: 201

{
    "message": "group is removed successfully"
}

The document in API.md:

Parameters
{
  "externalName": "the external group name binding with the group in OpenPAI"
}

We don't need the parameters when call the delete group API.

POST /api/v2/group

Response:

Status: 201

{
    "message": "group is created successfully"
}

Same with the document.

PUT /api/v2/group/:groupname/externalname

Response:

Status: 201

{
    "message": "update group externalNameData data successfully."
}

Same with the document.

GET /api/v2/group/:groupname/userlist

Response:

Status: 200

[
    {
        "username": "<user name>",
        "clusterAdmin": true | false
    },
    ...
]

No document in API.md

Jobs v1

GET /api/v1 (/user/:userName) /jobs

Response:

Status: 200

[
    {
        "name": "...",
        "username": "...",
        "state": "WAITING",
        "subState": "APPLICATION_WAITING",
        "executionType": "START",
        "retries": 0,
        "retryDetails": {
            "user": 0,
            "platform": 0,
            "resource": 0
        },
        "createdTime": ...,
        "completedTime": null,
        "appExitCode": null,
        "virtualCluster": "...",
        "totalGpuNumber": 1,
        "totalTaskNumber": 1,
        "totalTaskRoleNumber": 1
    },
    ...
]

Same with the document.

POST /api/v1/user/:userName/jobs

Response:

Status: 201

{
    "name": "...",
    "jobStatus": {
        "username": "...",
        "state": "WAITING",
        "subState": "FRAMEWORK_WAITING",
        "executionType": "START",
        "retries": 0,
        "retryDetails": {
            "user": 0,
            "platform": 0,
            "resource": 0
        },
        "createdTime": ...,
        "completedTime": null,
        "appId": null,
        "appProgress": null,
        "appTrackingUrl": null,
        "appLaunchedTime": null,
        "appCompletedTime": null,
        "appExitCode": null,
        "appExitSpec": null,
        "appExitDiagnostics": null,
        "appExitMessages": {
            "container": null,
            "runtime": null,
            "launcher": null
        },
        "appExitTriggerMessage": null,
        "appExitTriggerTaskRoleName": null,
        "appExitTriggerTaskIndex": null,
        "appExitType": null,
        "virtualCluster": "..."
    },
    "taskRoles": {}
}

The response in API.md:

Response if succeeded
Status: 202

{
  "message": "update job $jobName successfully"
}

Different with document in API.md.

GET /api/v1/user/:userName/jobs/:jobName

Response:

Status: 200
{
    "name": "...",
    "jobStatus": {
        "username": "...",
        "state": "SUCCEEDED",
        "subState": "FRAMEWORK_COMPLETED",
        "executionType": "START",
        "retries": 0,
        "retryDetails": {
            "user": 0,
            "platform": 0,
            "resource": 0
        },
        "createdTime": ...,
        "completedTime": ...,
        "appId": "a...",
        "appProgress": 1,
        "appTrackingUrl": "...",
        "appLaunchedTime": ...,
        "appCompletedTime": ...,
        "appExitCode": 0,
        "appExitSpec": {
            "code": 0,
            "phrase": "SUCCEEDED",
            "issuer": "USER_CONTAINER",
            "causer": "USER_CONTAINER",
            "type": "USER_SUCCESS",
            "stage": "COMPLETING",
            "behavior": "UNKNOWN",
            "reaction": "NEVER_RETRY",
            "repro": [
                "User program exits with exitcode 0"
            ]
        },
        "appExitDiagnostics": null,
        "appExitMessages": {
            "container": null,
            "runtime": null,
            "launcher": null
        },
        "appExitTriggerMessage": "All Tasks completed and no ApplicationCompletionPolicy has ever been triggered: TotalTaskCount: 1, FailedTaskCount: 0",
        "appExitTriggerTaskRoleName": null,
        "appExitTriggerTaskIndex": null,
        "appExitType": "SUCCEEDED",
        "virtualCluster": "default"
    },
    "taskRoles": {
        "main": {
            "taskRoleStatus": {
                "name": "main"
            },
            "taskStatuses": [
                {
                    "taskIndex": 0,
                    "taskState": "SUCCEEDED",
                    "containerId": "...",
                    "containerIp": "...",
                    "containerPorts": {
                        "http": "...",
                        "ssh": "..."
                    },
                    "containerGpus": 2,
                    "containerLog": "...",
                    "containerExitCode": 0
                }
            ]
        }
    }
}

Same with the document.

PUT /api/v1/user/:userName/jobs/:jobName

Response:

Status: 201

{
    "name": "...",
    "jobStatus": {
        "username": "...",
        "state": "WAITING",
        "subState": "FRAMEWORK_WAITING",
        "executionType": "START",
        "retries": 0,
        "retryDetails": {
            "user": 0,
            "platform": 0,
            "resource": 0
        },
        "createdTime": ...,
        "completedTime": null,
        "appId": null,
        "appProgress": null,
        "appTrackingUrl": null,
        "appLaunchedTime": null,
        "appCompletedTime": null,
        "appExitCode": null,
        "appExitSpec": null,
        "appExitDiagnostics": null,
        "appExitMessages": {
            "container": null,
            "runtime": null,
            "launcher": null
        },
        "appExitTriggerMessage": null,
        "appExitTriggerTaskRoleName": null,
        "appExitTriggerTaskIndex": null,
        "appExitType": null,
        "virtualCluster": "..."
    },
    "taskRoles": {}
}

It's said update job in the code.
Should use a new :jobName to avoid conflict, but the job name in job config don't have to change, looks like a different way to submit job without edit job config.

No document in API.md

DELETE /api/v1/user/:userName/jobs/:jobName

Response:

Status: 202

{
    "message": "deleted job pytorch-mnist-test12 successfully"
}

No document in API.md

PUT /api/v1/user/:userName/jobs/:jobName/executionType

Response:

Status: 202

{
    "message": "execute job <job name> successfully"
}

The status in API.md is 200, not 202.

GET /api/v1/user/:userName/jobs/:jobName/config

Response:

Status: 200

{
    "jobName": "...",
    "image": "openpai/pai.example.pytorch",
    "taskRoles": [
        {
            "name": "main",
            "taskNumber": 1,
            "cpuNumber": 4,
            "memoryMB": 8192,
            "gpuNumber": 1,
            "command": "..."
        }
    ]
}

Same with the document.

GET /api/v1/user/:userName/jobs/:jobName/ssh

Response:

Status: 200

{
    "containers": [
        {
            "id": "...",
            "sshIp": "...",
            "sshPort": "..."
        }
    ],
    "keyPair": {
        "folderPath": "...",
        "publicKeyFileName": "...",
        "privateKeyFileName": "...",
        "privateKeyDirectDownloadLink": "..."
    }
}

Same with the document.

Jobs v2

GET /api/v2/jobs

Response

Status: 500

{
    "message": "job.list is not a function"
}

No document in API.md

POST /api/v2/jobs

Response

Status: 202

{
    "status": 202,
    "message": "Update job <job name> for user <user name> successfully."
}

Document in API.md:

Response if succeeded
Status: 202

{
  "message": "update job $jobName successfully"
}

The message has a little different.

GET /api/v2/jobs/:frameworkName

Response:

Status: 200

{
    "summarizedFrameworkInfo": {
        "frameworkName": "...",
        "frameworkVersion": 10,
        "executionType": "START",
        "frameworkDescription": null,
        "userName": "core",
        "queue": "default",
        "totalGpuNumber": 1,
        "totalTaskNumber": 1,
        "totalTaskRoleNumber": 1,
        "firstRequestTimestamp": ...,
        "lastRequestTimestamp": ...,
        "frameworkState": "FRAMEWORK_COMPLETED",
        "frameworkRetryPolicyState": {
            "retriedCount": 0,
            "succeededRetriedCount": 0,
            "transientNormalRetriedCount": 0,
            "transientConflictRetriedCount": 0,
            "nonTransientRetriedCount": 0,
            "unKnownRetriedCount": 0
        },
        "frameworkCompletedTimestamp": ...,
        "applicationExitCode": 255
    },
    "aggregatedFrameworkRequest": {
        "frameworkRequest": {
            "frameworkName": "...",
            "frameworkDescriptor": {
                "description": null,
                "version": 10,
                "executionType": "START",
                "retryPolicy": {
                    "fancyRetryPolicy": true,
                    "maxRetryCount": 0
                },
                "parentFramework": null,
                "user": {
                    "name": "..."
                },
                "taskRoles": {
                    "worker": {
                        "taskNumber": 1,
                        "scaleUnitNumber": 1,
                        "scaleUnitTimeoutSec": 0,
                        "taskRetryPolicy": {
                            "fancyRetryPolicy": false,
                            "maxRetryCount": 0
                        },
                        "applicationCompletionPolicy": {
                            "minFailedTaskCount": 1,
                            "minSucceededTaskCount": null
                        },
                        "taskService": {
                            "version": 0,
                            "entryPoint": "...",
                            "sourceLocations": [
                                "..."
                            ],
                            "resource": {
                                "cpuNumber": 1,
                                "memoryMB": 16384,
                                "portDefinitions": {
                                    "ssh": {
                                        "start": 0,
                                        "count": 1
                                    },
                                    "http": {
                                        "start": 0,
                                        "count": 1
                                    }
                                },
                                "diskType": "HDD",
                                "diskMB": 0,
                                "gpuNumber": 1,
                                "gpuAttribute": 0
                            }
                        },
                        "platformSpecificParameters": {
                            "taskNodeLabel": null,
                            "taskNodeGpuType": null,
                            "samePortAllocation": false
                        }
                    }
                },
                "platformSpecificParameters": {
                    "amResource": {
                        "cpuNumber": 1,
                        "memoryMB": 1024,
                        "portDefinitions": {},
                        "diskType": "HDD",
                        "diskMB": 0,
                        "gpuNumber": 0,
                        "gpuAttribute": 0
                    },
                    "amNodeLabel": null,
                    "taskNodeLabel": null,
                    "taskNodeGpuType": null,
                    "queue": "default",
                    "containerConnectionMaxLostCount": -2,
                    "containerConnectionMaxExceedCount": 2,
                    "antiaffinityAllocation": false,
                    "gangAllocation": true,
                    "skipLocalTriedResource": true,
                    "amType": "DEFAULT",
                    "agentUseHeartbeat": false,
                    "agentHeartbeatIntervalSec": 30,
                    "agentExpiryIntervalSec": 180,
                    "agentUseHealthCheck": false,
                    "taskServiceHealthCheck": null
                }
            },
            "launchClientType": "UNKNOWN",
            "launchClientHostName": "...",
            "launchClientUserName": "UNKNOWN",
            "firstRequestTimestamp": ...,
            "lastRequestTimestamp": ...
        },
        "overrideApplicationProgressRequest": null,
        "migrateTaskRequests": null
    },
    "aggregatedFrameworkStatus": {
        "frameworkStatus": {
            "frameworkName": "...",
            "frameworkVersion": 10,
            "frameworkState": "FRAMEWORK_COMPLETED",
            "frameworkRetryPolicyState": {
                "retriedCount": 0,
                "succeededRetriedCount": 0,
                "transientNormalRetriedCount": 0,
                "transientConflictRetriedCount": 0,
                "nonTransientRetriedCount": 0,
                "unKnownRetriedCount": 0
            },
            "frameworkCreatedTimestamp": ...,
            "frameworkCompletedTimestamp": ...,
            "applicationId": "...",
            "applicationProgress": 1,
            "applicationTrackingUrl": "...",
            "applicationLaunchedTimestamp": ...,
            "applicationCompletedTimestamp": ...,
            "applicationExitCode": 255,
            "applicationExitDescription": "...",
            "applicationExitDiagnostics": "...",
            "applicationExitType": "UNKNOWN",
            "applicationExitTriggerMessage": "...",
            "applicationExitTriggerTaskRoleName": "worker",
            "applicationExitTriggerTaskIndex": 0
        },
        "aggregatedTaskRoleStatuses": {
            "worker": {
                "taskRoleStatus": {
                    "taskRoleName": "worker",
                    "taskRoleRolloutStatus": {
                        "overallRolloutServiceVersion": null,
                        "overallRolloutStatus": "UNKNOWN",
                        "overallRolloutStartTimestamp": null,
                        "overallRolloutEndTimestamp": null,
                        "currentRolloutScaleUnit": null,
                        "currentRolloutTaskIndexes": null,
                        "currentRolloutStatus": "UNKNOWN",
                        "currentRolloutStartTimestamp": null,
                        "currentRolloutEndTimestamp": null
                    },
                    "frameworkVersion": 10
                },
                "taskStatuses": {
                    "taskRoleName": "worker",
                    "taskStatusArray": [
                        {
                            "taskIndex": 0,
                            "taskRoleName": "worker",
                            "taskState": "TASK_COMPLETED",
                            "taskRetryPolicyState": {
                                "retriedCount": 0,
                                "succeededRetriedCount": 0,
                                "transientNormalRetriedCount": 0,
                                "transientConflictRetriedCount": 0,
                                "nonTransientRetriedCount": 0,
                                "unKnownRetriedCount": 0
                            },
                            "taskCreatedTimestamp": ...,
                            "taskCompletedTimestamp": ...,
                            "taskServiceStatus": {
                                "serviceVersion": 0
                            },
                            "containerId": "...",
                            "containerHost": "...",
                            "containerIp": "...",
                            "containerPorts": "ssh:...;http:...;",
                            "containerGpus": 1,
                            "containerLogHttpAddress": "...",
                            "containerConnectionLostCount": 0,
                            "containerIsDecommissioning": null,
                            "containerLaunchedTimestamp": ...,
                            "containerCompletedTimestamp": ...,
                            "containerExitCode": 255,
                            "containerExitDescription": "...",
                            "containerExitDiagnostics": "...",
                            "containerExitType": "UNKNOWN"
                        }
                    ],
                    "frameworkVersion": 10
                }
            }
        }
    }
}

It's said Get job in the code.
No document in API.md

PUT /api/v2/jobs/:frameworkName/executionType

Response:

Status: 500

{
    "message": "Cannot read property 'username' of undefined"
}

No document in API.md

GET /api/v2/jobs/:frameworkName/config

Response:

Status: 500

protocolVersion: 2
name: ...
type: job
prerequisites:
  - protocolVersion: 2
    ...

taskRoles:
  ...

Same with the document.

GET /api/v2/jobs/:frameworkName/ssh

Response:

Status: 500

{
    "message": "job.getSshInfo is not a function"
}

No document in API.md

Redirect /api/v2/user/:username/jobs => /api/v1/user/:username/jobs

The request for /api/v2/user/:username/jobs will be redirect to /api/v1/user/:username/jobs.

No document in API.md

Token

POST /api/v1/token

Response:

Status: 200

{
    "user": "<username>",
    "token": "<token string>",
    "admin": true | false,
    "hasGitHubPAT": true | false
}

No document for hasGitHubPAT from the response.

User v1

GET /api/v1/user/:username

Response:

Status: 200

{
    "username": "...",
    "grouplist": [
        "...",
        ...
    ],
    "email": "",
    "extension": {
        "virtualCluster": [
            "..."
        ]
    },
    "admin": true,
    "virtualCluster": [
        "...",
        ...
    ]
}

Get user info.
No document in API.md

User v2

GET /api/v2/user/:username

Response:

Status: 200

{
    "username": "...",
    "grouplist": [
        "...",
        ...
    ],
    "email": "",
    "extension": {
        "virtualCluster": [
            "..."
        ]
    },
    "admin": true,
    "virtualCluster": [
        "...",
        ...
    ]
}

Get user info.
No document in API.md

GET /api/v2/user

Response:

Status: 200

[
    {
        "username": "...",
        "grouplist": [
            "..."
        ],
        "email": "",
        "extension": {},
        "admin": false,
        "virtualCluster": [
            "..."
        ]
    },
    ...
]

List all users.
No document in API.md

PUT /api/v2/user/:username/extension

Response:

Status: 201

{
    "message": "Update user extension data successfully."
}

Same with document.

DELETE /api/v2/user/:username

Response:

Status: 200

{
    "message": "user is removed successfully"
}

Same with document.

PUT /api/v2/user/:username/virtualcluster

Response:

Status: 201

{
    "message": "Update user virtualCluster data successfully."
}

Same with document.

PUT /api/v2/user/:username/password

Response:

Status: 201

{
    "message": "update user password successfully."
}

Same with document.

POST /api/v2/user

Response:

Status: 201

{
    "message": "User is created successfully"
}

Same with document.

PUT /api/v2/user/:username/email

Request:

{
  "email": "<new email>"
}

Response:

Status: 201

{
    "message": "Update user email data successfully."
}

The document in API.md:

Parameters
{
  "email": "Update user email data successfully."
}

Response if succeeded
Status: 201

{
  "message": "Update user virtualCluster data successfully."
}

Some mistake in the document.

PUT /api/v2/user/:username/admin

Response:

Status: 201

{
    "message": "Update user admin permission successfully."
}

Same with document.

PUT /api/v2/user/:username/grouplist

Response:

Status: 201

{
    "message": "update user grouplist successfully."
}

Same with document.

PUT /api/v2/user/:username/group

Response:

Status: 201

{
    "message": "User <user name> is added into group <group name>"
}

Same with document.

DELETE /api/v2/user/:username/group

Response:

Status: 201

{
    "message": "User core11 is removed from group newGroup1"
}

Same with document.

Virtual-Cluster v1

GET /api/v1/virtual-clusters

Response:

Status: 200

{
    "<vc name>": {
        "capacity": ...,
        "maxCapacity": ...,
        "usedCapacity": ...,
        "numActiveJobs": 3,
        "numJobs": 3,
        "numPendingJobs": 0,
        "resourcesUsed": {
            "memory": ..,
            "vCores": ...,
            "GPUs": 0
        },
        "status": "RUNNING",
        "dedicated": false,
        "resourcesTotal": {
            "vCores": ...,
            "memory": ...,
            "GPUs": ...
        },
        "nodeList": [...]
    },
    ...
}

Same with document.

GET /api/v1/virtual-clusters/:vcName

Response:

Status: 200

{
    "capacity": ...,
    "maxCapacity": ...,
    "usedCapacity": ...,
    "numActiveJobs": 3,
    "numJobs": 3,
    "numPendingJobs": 0,
    "resourcesUsed": {
        "memory": ..,
        "vCores": ...,
        "GPUs": 0
    },
    "status": "RUNNING",
    "dedicated": false,
    "resourcesTotal": {
        "vCores": ...,
        "memory": ...,
        "GPUs": ...
    },
    "nodeList": [...]
}

Same with document.

PUT /api/v1/virtual-clusters/:vcName

Response:

Status: 201

{
    "message": "create vc: <vc name> to capacity: <capicity> successfully"
}

or

{
    "message": "update vc: <vc name> to capacity: <capicity> successfully"
}

Same with document.

DELETE /api/v1/virtual-clusters/:vcName

Response:

Status 201

{
    "message": "Remove vc: <vc name> successfully"
}

Same with document.

PUT /api/v1/virtual-clusters/:vcName/status

Response:

Status 201

{
    "message": "active vc <vc name> successfully"
}

or

{
    "message": "stop vc <vc name> successfully"
}

Document in API.md:

Response if succeeded
Status: 201

{
  "message": "Update vc: $vcName to status: $vcStatus successfully."
}

The response message is different.

Virtual-Cluster v2

GET /api/v2/virtual-clusters

Response:

Status: 200

{
    "<vc name>": {
        "capacity": ...,
        "maxCapacity": ...,
        "usedCapacity": ...,
        "numActiveJobs": 3,
        "numJobs": 3,
        "numPendingJobs": 0,
        "resourcesUsed": {
            "memory": ..,
            "vCores": ...,
            "GPUs": 0
        },
        "status": "RUNNING",
        "dedicated": false,
        "resourcesTotal": {
            "vCores": ...,
            "memory": ...,
            "GPUs": ...
        },
        "nodeList": [...]
    },
    ...
}

No document in API.md

GET /api/v2/virtual-clusters/nodeResource

Response:

Status: 200
{
    "<ip address1>": {
        "gpuTotal": 4,
        "gpuUsed": 0,
        "gpuAvaiable": 4
    },
    "<ip address2>": {
        "gpuTotal": 4,
        "gpuUsed": 0,
        "gpuAvaiable": 4
    },
    ...
}

No document in API.md

GET /api/v2/virtual-clusters/:virtualClusterName

Response:

Status: 200

{
    "capacity": ...,
    "maxCapacity": ...,
    "usedCapacity": ...,
    "numActiveJobs": 3,
    "numJobs": 3,
    "numPendingJobs": 0,
    "resourcesUsed": {
        "memory": ..,
        "vCores": ...,
        "GPUs": 0
    },
    "status": "RUNNING",
    "dedicated": false,
    "resourcesTotal": {
        "vCores": ...,
        "memory": ...,
        "GPUs": ...
    },
    "nodeList": [...]
}

No document in API.md

PUT /api/v2/virtual-clusters/:virtualClusterName

Response:

Status: 201

{
    "status": 201,
    "message": "Create virtual cluster <vc name> to capacity <capicity> successfully."
}

or

{
    "status": 201,
    "message": "Update virtual cluster <vc name> to capacity <capicity> successfully."
}

A little different from v1.
No document in API.md

DELETE /api/v2/virtual-clusters/:virtualClusterName

Response:

Status: 201

{
    "status": 201,
    "message": "Remove virtual cluster <vc name> successfully."
}

No document in API.md

PUT /api/v2/virtual-clusters/:virtualClusterName/status

Response:

Status: 201

{
    "status": 201,
    "message": "Activate virtual cluster <vc name> successfully."
}

or

{
    "status": 201,
    "message": "Stop virtual cluster <vc name> successfully."
}

No document in API.md

GET /api/v2/virtual-clusters/:virtualClusterName/resourceUnits

Response:

Status: 204

{
    "code": "NotImplementedError",
    "message": "getResourceUnits not implemented in yarn"
}

No document in API.md

Info

GET /api/v1

Response:

Status: 200

{
    "name": "PAI RESTful API",
    "version": "v0.14.0",
    "launcherType": "yarn",
    "authnMethod": "basic"
}

Same with document.

[fanyangCS]

this has completed under the new API refactoring effort (and swagger spec)