Provisioning: group API

Quản lý nhóm
===============

Giới thiệu
------------

Tài liệu này mô tả chi tiết các endpoint liên quan đến quản lý nhóm trong hệ thống OBM dự phòng.

Định dạng mặc định là JSON.

Định danh
-------

Ở đây chúng ta lấy **/provisioning/{apiVersion}/{domainUUID}** làm URI cơ bản cho điểm cuối REST. Gọi tắt là {baseURI}.
Ký hiệu {serverBaseURL} là URL gốc của server REST, eg http://1.2.3.4:8080/
Ký hiệu {batchId} đại diện cho số lô duy nhất
Ký hiệu {batchStatus} là trạng thái của lô, lấy từ danh sách trạng thái.
Ký hiệu {apiVersion} đại diện cho chuỗi liên kết với phiên bản của API client muốn dùng (eg. "v1")
Ký hiệu {groupId} là id duy nhất của nhóm.
Ký hiệu {userId} là id người dùng duy nhất.

Tài nguyên sử dụng
--------------

### Tài nguyên nhóm (Group Resource)

Ví dụ:

{
"id": "84109ac4-9979-4692-aee9-0a9ab66621ca",
"name": "admin",
"description": "System Administrators",
"members": { group member resource }
}

Thuộc tính cần thiết:

| Tên thuộc tính | Kiểu giá trị | Mô tả |
| ------------- | ---------- | --------------------------------------------- |
| id | string | id duy nhất biểu diễn tài nguyên nhóm |
| name | string | Tên ngắn của nhóm |

Thuộc tính tùy chọn:

| Tên thuộc tính | Kiểu giá trị | Mô tả |
| ------------- | ---------- | --------------------------------------------- |
| description | string | Mô tả chi tiết nhóm |
| members | object | Một tài nguyên thành viên với các thành viên của nhóm|

### Tài nguyên thành viên trong nhóm

Ví dụ:

{
"users": [
group user resource
],
"subgroups": [
group user resource
],
}

Thuộc tính tùy chọn:

| Tên thuộc tính | Kiểu giá trị | Mô tả |
| ------------- | ---------- | --------------------------------------------- |
| users[] | list | Danh sách thành viên trong nhóm |
| subgroups[] | list | Danh sách nhóm con |

Tạo một nhóm
----------------

### Định nghĩa

Endpoint này để tạo một nhóm có id do server tự sinh. Nếu muốn tạo một nhóm có id thì dùng chức năng cập nhật.

### Thông tin REST

* phương thức: POST
* uri: {baseURI}/batches/{batchId}/groups
* tham số truy vấn: none
* Thân yêu cầu: cấu trúc dữ liệu json mô tả các thuộc tính của nhóm.

* mã trả về:
* 201 nếu tạo nhóm thành công.
* 400 là yêu cầu xấu nếu dữ liệu của client không hợp lệ.
* 5XX xảy ra lỗi.

* Nội dung trả về:
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Tạo một nhóm có id
------------------------------------------------

Xem "Tạo hoặc sửa nhóm".

Tạo hoặc sửa nhóm
-----------------------------

### Định nghĩa

Endpoint này để tạo một nhóm có {groupId} hoặc chỉnh sửa một nhóm đang tồn tại.

### Thông tin REST

* phương thức: PUT
* uri: {baseURI}/batches/{batchId}/groups/{groupId}
* tham số truy vấn: none
* Thân yêu cầu: cấu trúc dữ liệu json mô tả các thuộc tính của nhóm.

* mã trả về:
* 200 Thành công nếu tồn tại nhóm này và các thông tin được cập nhật thành công.
* 201 nếu tạo nhóm thành công. và các thông tin được cập nhật thành công.
* 400 yêu cầu xấu nếu dữ liệu của client không hợp lệ.
* 5XX xảy ra lỗi

* Nội dung trả về:
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Chỉnh sửa một phần thông tin của nhóm
------------------------------------------

### Định nghĩa

Dùng đề chỉnh sửa một nhóm đang tồn tại.

### Thông tin REST

* phương thức: PATCH
* uri: {baseURI}/batches/{batchId}/groups/{groupId}
* tham số truy vấn: none
* Thân yêu cầu: cấu trúc dữ liệu json mô tả các thuộc tính của nhóm

* mã trả về:
* 200 hành công nếu sửa thành công đối tượng này
* 400 yêu cầu xấu nếu dữ liệu của client không hợp lệ
* 5XX xảy ra lỗi

* Nội dung trả về:
Nếu thành công: toàn bộ thông tin đã chỉnh sửa
Nếu lỗi: xem "standard errors"

Xóa một nhóm
----------------

### Định nghĩa

Endpoint này để xóa một nhóm bằng cách dùng {groupId}.

### Thông tin REST

* phương thức: DELETE
* uri: {baseURI}/batches/{batchId}/groups/{groupId}
* tham số truy vấn:
* expunge - nếu đúng, nhóm sẽ bị xóa và không còn được lưu lại
* Thân yêu cầu: none

* return code:
* 200 Success nếu nhóm đã bị xóa
* 404 Not Found nếu không tìm thấy groupId hoặc batchId
* 5XX xảy ra lỗi

* Nội dung trả về:
Nếu thành công: toàn bộ thông tin đã chỉnh sửa
Nếu lỗi: xem "standard errors"ề

Gán nhóm cho người dùng
--------------------------------

### Định nghĩa

Mục đích để tạo danh sách người dùng vào một nhóm.

### Thông tin REST

* phương thức: PUT
* uri: {baseURI}/batches/{batchId}/groups/{groupId}/members
* tham số truy vấn: none
* Thân yêu cầu:

{
"users": []
"subgroups": []
}

* mã trả về:
* 200 Success nếu gán thành công
* 400 Bad Request yêu cầu xấu nếu dữ liệu của client không hợp lệ
* 404 Not Found nếu không tìm thấy groupId hoặc batchId
* 5XX xảy ra lỗi

* nội dung trả về:
Nếu thành công: toàn bộ thông tin đã chỉnh sửa
Nếu lỗi: xem "standard errors"ề

Thêm một người dùng vào nhóm
------------------------

### Định nghĩa

Mục đích để thêm một người dùng mới vào một nhóm.

### Thông tin REST

* phương thức: PUT
* uri: {baseURI}/batches/{batchId}/groups/{groupId}/users/{userId}
* tham số truy vấn: none
* Thân yêu cầu none

* mã trả về:
* 200 Success nếu người dùng đã ở trong nhóm
* 201 Created nếu người dùng đã được thêm vào nhóm
* 404 Not Found nếu không tìm thấy userId, groupId hoặc batchId
* 5XX error khi có lỗi

* Nội dung trả về:
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Tạo nhóm nhỏ trong một nhóm
----------------------------

### Định nghĩa

Mục đích để thêm một nhóm nhỏ mới trong một nhóm.

### Thông tin REST

* phương thức:: PUT
* uri: {baseURI}/batches/{batchId}/groups/{groupId}/subgroups/{groupId}
* tham số truy vấn: none
* Thân yêu cầu: none

* mã trả về::
* 200 Success nếu nhóm con đó đã có trong nhóm.
* 201 Created nếu nhóm con đã được thêm
* 404 Not Found nếu không tìm thấy groupId hoặc batchId
* 5XX errors khi xảy ra lỗi

* Nội dung trả về
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Xóa một người dùng khỏi nhóm
----------------------------

### Định nghĩa

Mục đích để xóa một người dùng khỏi nhóm.

### Thông tin REST

* phương thức: DELETE
* uri: {baseURI}/batches/{batchId}/groups/{groupId}/users/{userId}
* tham số truy vấn: none
* Thân yêu cầu: none

* mã trả về:
* 200 Success nếu người dùng đã bị xóa
* 404 Not Found nếu không tìm được userId, groupId hoặc batchId
* 5XX errors khi có lỗi

* Nội dung trả về:
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Xóa một nhóm con khỏi nhóm
--------------------------------

### Định nghĩa

Mục đích để xóa một nhóm người dùng nhỏ khỏi nhóm.

### Thông tin REST

* phương thức: DELETE
* uri: {baseURI}/batches/{batchId}/groups/{groupId}/subgroup/{groupId}
* tham số truy vấn: none
* Thân yêu cầu: none

* mã trả về:
* 200 Success nếu nhóm con đã bị xóa
* 404 Not Found nếu không tìm thấy groupId hoặc batchId
* 5XX errors khi có lỗi

* Nội dung trả về:
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Lấy thông tin nhóm
---------------

### Định nghĩa

Dùng để truy vấn thông tin một nhóm cụ thể.

### Thông tin REST

* phương thức: GET
* uri: {baseURI}/groups/{groupId}
* tham số truy vấn:
* expandDepth - A number value specifying how deep users and groups are
expanded. -1 means infinite recursion, 0 means do not specify
users or groups, any other other number is the level of
recursion while expanding.
* Thân yêu cầu: none

* mã trả về:
* 200 Success nếu tìm thấy nhóm
* 404 Not found nếu không tìm thấy
* 5XX errors khi lỗi
* Phần đầu HTTP: none

* Nội dung trả về:
Nếu thành công: nội dung trống
Nếu lỗi: xem "standard errors"

Lấy danh sách thành viên nhóm con của nhóm
---------------------------------------

### Định nghĩa

This endpoint retrieves all subgroups contained in a group

### Thông tin REST

* phương thức: GET
* uri: {baseURI}/groups/{groupId}/subgroups
* tham số truy vấn: none
* Thân yêu cầu: none

* mã trả về:
* 200 Success nếu tìm thấy nhóm
* 404 Not found nếu không tìm thấy
* 5XX errors khi lỗi
* Phần đầu HTTP: none
* Nội dung trả về:
Nếu thành công: danh sách người dùng và các nhóm con của nhóm.
Nếu lỗi: xem "standard errors"

Lấy các thành viên nhóm

### Định nghĩa

Dùng truy vấn tất cả người dùng trong nhóm.

### Thông tin REST

* phương thức: GET
* uri: {baseURI}/groups/{groupId}/users
* tham số truy vấn: none
* Thân yêu cầu: none

* mã trả về:
* 200 Success nếu tìm thấy nhóm
* 404 Not found nếu không tìm thấy
* 5XX errors khi lỗi
* Phần đầu HTTP: none
* Nội dung trả về:
Nếu thành công: danh sách người dùng
Nếu lỗi: xem "standard errors"

Quản lý profile
=================

Liệt kê profile
----------------

### Định nghĩa

Dùng để lấy danh sách tất cả profile hiện có.

### Thông tin REST

* phương thức: GET
* uri: {baseURI}/profiles
* tham số truy vấn: none
* Thân yêu cầu: none

* mã trả về:
* 200 Success nếu lấy thành công thông tin profile
* 5XX errors khi có lỗi
* Phần đầu HTTP: none
* Nội dung trả về:
Nếu thành công: thông tin profile
Nếu lỗi: xem "standard errors"
Popular Off-White