From fc1b7b391db9549844e19f7cb8613ba4acd467af Mon Sep 17 00:00:00 2001 From: ryankert Date: Sat, 6 Jul 2024 10:54:31 +0800 Subject: [PATCH 1/2] cleanup api docs --- docs/api/cluster.md | 10 --- docs/api/scheduler.md | 172 +++++++++--------------------------------- 2 files changed, 37 insertions(+), 145 deletions(-) diff --git a/docs/api/cluster.md b/docs/api/cluster.md index 35e98dac44f..805a109bcbd 100644 --- a/docs/api/cluster.md +++ b/docs/api/cluster.md @@ -67,13 +67,3 @@ As an example, here is a response from a cluster with 1 resource manager. ### Error response **Code** : `500 Internal Server Error` - -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index 482b98dfb24..ff8b376a125 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -131,15 +131,7 @@ Returns general information and statistics about a partition. **Code** : `500 Internal Server Error` -**Content examples** -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## PlacementRules @@ -299,17 +291,11 @@ For the default queue hierarchy (only `root.default` leaf queue exists) a simila ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid, missing partition name) -**Content examples** +**Code** : `404 Not Found` (Partition not found) -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` +**Code** : `500 Internal Server Error` ## Applications @@ -335,6 +321,14 @@ For active state, can narrow the result by status query parameters(case-insensit The content of the application object is the same as Queue Applications. See [Queue Applications](#queue-applications) for details. +### Error Response + +**Code** : `400 Bad Request` (URL query is invalid) + +**Code** : `404 Not Found` (Partition not found) + +**Code** : `500 Internal Server Error` + ### Queue applications Fetch all Applications for the given Partition/Queue combination and displays general information about the applications like used resources, queue name, submission time and allocations. @@ -575,17 +569,12 @@ In the example below there are three allocations belonging to two applications, ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid) -**Content examples** +**Code** : `404 Not Found` (Partition or Application not found) + +**Code** : `500 Internal Server Error` -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## Application @@ -733,17 +722,12 @@ Field `uuid` has been deprecated, would be removed from below response in YUNIKO ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid) -**Content examples** +**Code** : `404 Not Found` (Partition or Application not found) + +**Code** : `500 Internal Server Error` -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## UsersTracker ### Get users usage tracking information @@ -840,17 +824,9 @@ Fetch all users usage given a Partition and displays general information about t ``` ### Error response -**Code** : `500 Internal Server Error` -**Content examples** +**Code** : `500 Internal Server Error` -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## UserTracker ### Get specific user usage tracking information @@ -909,17 +885,11 @@ Fetch specific user usage given a Partition and displays general information abo ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid) -**Content examples** +**Code** : `404 Not Found` (User not found) -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` +**Code** : `500 Internal Server Error` ## GroupsTracker ### Get groups usage tracking information @@ -1014,15 +984,6 @@ Fetch all groups usage given a Partition and displays general information about **Code** : `500 Internal Server Error` -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## GroupTracker ### Get specific group usage tracking information @@ -1080,17 +1041,11 @@ Fetch specific group usage given a Partition and displays general information ab ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid) -**Content examples** +**Code** : `404 Not Found` (Group not found) -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` +**Code** : `500 Internal Server Error` ## Nodes @@ -1296,17 +1251,11 @@ Here you can see an example response from a 2-node cluster having 3 allocations. ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid) -**Content examples** +**Code** : `404 Not Found` (Partition not found) -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` +**Code** : `500 Internal Server Error` ## Node @@ -1418,17 +1367,11 @@ Node details include host and rack name, capacity, resources, utilization, and a ### Error response -**Code** : `500 Internal Server Error` +**Code** : `400 Bad Request` (URL query is invalid) -**Content examples** +**Code** : `404 Not Found` (Partition or Node not found) -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` +**Code** : `500 Internal Server Error` ## Node utilization @@ -1476,15 +1419,6 @@ Show how every node is distributed with regard to dominant resource utilization. **Code** : `500 Internal Server Error` -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## Node utilizations @@ -1552,15 +1486,6 @@ Show the nodes utilization of different types of resources in a cluster. **Code** : `500 Internal Server Error` -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## Goroutines info @@ -1643,15 +1568,6 @@ created by os/signal.init.0 **Code** : `500 Internal Server Error` -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## Metrics @@ -1705,6 +1621,9 @@ yunikorn_scheduler_vcore_nodes_usage{range="(80%,90%]"} 0 yunikorn_scheduler_vcore_nodes_usage{range="(90%,100%]"} 0 yunikorn_scheduler_vcore_nodes_usage{range="[0,10%]"} 0 ``` +### Error response + +**Code** : `500 Internal Server Error` ## Configuration validation @@ -1892,16 +1811,6 @@ Endpoint to retrieve historical data about the number of total applications by t **Code** : `500 Internal Server Error` -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` - ## Container history Endpoint to retrieve historical data about the number of total containers by timestamp. @@ -1947,15 +1856,6 @@ Endpoint to retrieve historical data about the number of total containers by tim **Code** : `500 Internal Server Error` -**Content examples** - -```json -{ - "status_code": 500, - "message": "system error message. for example, json: invalid UTF-8 in string: ..", - "description": "system error message. for example, json: invalid UTF-8 in string: .." -} -``` ## Endpoint healthcheck @@ -2180,5 +2080,7 @@ The number of active connections is limited. The default setting is 100 connecti ### Error responses **Code** : `400 Bad Request` (URL query is invalid) + **Code** : `503 Service Unavailable` (Too many active streaming connections) + **Code** : `500 Internal Server Error` From 64ed6b4ea078af15b54d2c8fba31b314a0c44efa Mon Sep 17 00:00:00 2001 From: ryankert Date: Sun, 7 Jul 2024 09:18:39 +0800 Subject: [PATCH 2/2] code review --- docs/api/scheduler.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index ff8b376a125..b944f297772 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -571,7 +571,7 @@ In the example below there are three allocations belonging to two applications, **Code** : `400 Bad Request` (URL query is invalid) -**Code** : `404 Not Found` (Partition or Application not found) +**Code** : `404 Not Found` (Partition or Queue not found) **Code** : `500 Internal Server Error` @@ -1621,9 +1621,6 @@ yunikorn_scheduler_vcore_nodes_usage{range="(80%,90%]"} 0 yunikorn_scheduler_vcore_nodes_usage{range="(90%,100%]"} 0 yunikorn_scheduler_vcore_nodes_usage{range="[0,10%]"} 0 ``` -### Error response - -**Code** : `500 Internal Server Error` ## Configuration validation