Dự liệu: user API

OBM provisioning API

Users API
=========

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

Tài liệu này nêu chi tiết các endpoint liên quan đến quản lý users trong OBM.

Đị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 {userId} đại diện duy nhất của user
Ký hiệu {apiVersion} đại diện của 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 {domainUUID} đại diện duy nhất của domain đang làm viêc.

Cấu trúc và kiểu dữ liệu
----------------

### datetime

The _datetime_ data type , mở rộng định dạng ISO 8601:2004.

### User

{

// Mandatory fields

id: string, // userobm_ext_id
login: string, // userobm_login
lastname: string, // userobm_lastname
profile: string, // userobm_perms

// Optional fields
// The following fields can be ommitted in PATCH,PUT and POST requests

firstname: string, // userobm_firstname
commonname: string, // userobm_commonname
password: string, // userobm_password, only PLAIN supported
kind: string, // userobm_kind
title: string, // userobm_title
description: string, // userobm_description
company: string, // userobm_company
service: string, // userobm_service
direction: string, // userobm_direction
addresses: [string], // userobm_address1, 2 and 3, only 3 addresses supported
town: string, // userobm_town
zipcode: string, // userobm_zipcode
business_zipcode: string, // userobm_expresspostal
country: string, // userobm_country_iso3166
phones: [string], // userobm_phone1 and 2, only 2 phone numbers supported
mobile: string, // userobm_mobile
faxes: [string], // userobm_fax1 and 2, only 2 fax numbers supported
mail_quota: integer, // userobm_mail_quota, default 0 (no quota)
mail_server: string, // host.host_name, with the corresponding host_id assigned to userobm_mail_server_id
mails: [string], // a list of emails, with or without domain
timecreate: datetime, // time of creation in the OBM database - field ignored for PUT/POST/PATCH
timeupdate: datetime, // time of update in the OBM database - field ignored for PUT/POST/PATCH
groups: [{ "id": {userId}, "url": string }, {}, ...] // list of group identifiers and URLs - this is a read-only attribute and is ignored for PUT/PATCH/POST requests

}

Tao người dùng
----------------

### Definition

This endpoint creates a new user.

### Thông tin REST

* method: POST
* uri: {baseURI}/batches/{batchId}/users
* tham số truy vấn: none
* thân yêu cầu : __User__ data structure
* mã trả vể: 201 khi thành công, 4XX có vấn đề về dữ liệu, 5xx khi lỗi
* phần đầu HTTP:
Location: {serverBaseURL}/provisioning/{apiVersion}/users/{userId}

* nội dung trả về khi thành công: none
* nội dung trả về khi lỗi: xem "standard errors"

Chỉnh sửa user
-------------------------

### Định nghĩa

Dùng chỉnh sửa thông tin một user.
Hành động này thay thế hoàn toàn người dùng bằng các thông tin trong gói tin yêu cầu. Để sửa cucj bộ một vài chi tiết của người dùng, xem _Sửa thông tin cục bộ của user_.

### Thông tin REST

* phương thức: PUT
* uri: {baseURI}/batches/{batchId}/users/{userId}
* tham số truy vấn: none
* thân yêu cầu: a __User__ data structure
* mã trả về: 200 khi thành công, 4XX có vấn đề về dữ liệu, 404 khi không tồn tại {userId}, 5xx khi lỗi
* nội dung trả về khi thành công: none
* nội dung trả về khi lỗi: xem "standard errors"

Sửa thông tin cục bộ của user
-------------------------

### Định nghĩa

Dùng để chỉnh sửa, thêm, hoặc thay thế một số trường của user. Để thay thế xem thêm _Chỉnh sửa user_.

### Thông tin REST

* phương thức: PATCH
* uri: {baseURI}/batches/{batchId}/users/{userId}
* tham số truy vấn: none
* thân yêu cầu: a (partial) __User__ data structure
* mã trả về: 200 khi thành công, 4XX có vấn đề về dữ liệu, 404 khi không tồn tại {userId}, 5xx khi lỗi
* nội dung trả về khi thành công: none
* nội dung trả về khi lỗi: xem "standard errors"

Lưu hoặc xóa một user
-------------------

### Định nghĩa

Dùng để lưu hoặc xóa một user, phụ thuộc vào tham số truy vấn.

### Thông tin REST

* phương thức: DELETE
* endpoint: {baseURI}/batches/{batchId}/users/{userId}
* tham số truy vấn:

| Parameter | Description | Data type | Default value |
| ----- |
| expunge | Xác định xóa vĩnh viễn hoặc lưu trữ | Boolean | False |

* mã trả về: 200 khi thành công, 5xx khi lỗi, 404 khi không tồn tại {userId}
* nội dung trả về khi thành công: none
* nội dung trả về khi lỗi: xem "standard errors"

Đại diện của người sử dụng
-------------------

### Định nghĩa

Dùng lấy thông tin đại diện của user trong database.

### Thông tin REST

* phương thức: GET
* endpoint: {baseURI}/users/{userId}
* tham số truy vấn: none
* mã trả về: 200 khi thành công, 5xx khi lỗi, 404 khi không tồn tại {userId}
* nội dung trả về khi thành công: a __User__ data structure
* nội dung trả về khi lỗi: xem "standard errors"

Liệt kê tất cả người dùng
-----------------

### Định nghĩa

Trả về danh sách tất cả các users.

### Thông tin REST

* phương thức: GET
* endpoint: {baseURI}/users/
* tham số truy vấn: none
* mã trả về: 200 khi thành công, 5xx khi lỗi
* nội dung trả về

{
users: [{ "id": {userId}, "url": string }, {}, ...] // List of user identifiers and URLs
}

* nội dung trả về khi lỗi: xem "standard errors"Gifts for Runners