BackEnd API Document : USER SYSTEM (KO_KR)
작성자 : LimeCake
모든 REQUEST는 POST 방식을 전제로 한다.
개발 단계에서는 GET 방식으로 테스트를 위한 접근도 가능하다.
모든 RESULT는 JSONObject 로 반환된다.
만일 JSONObject로 파싱 시 exception catch 될 경우 서버 에러로 간주한다.
string 인코딩은 UTF-8 을 기본으로 한다.
https://api.devx.kr/GotGan/v1/{API명}
로그인을 담당하는 API
관리자의 시스템 로그인
일반 사용자의 시스템 로그인
user_id (string) [필수 인자]
유저가 로그인할 아이디를 의미한다.
user_pw (string) [필수 인자]
유저가 로그인할 비밀번호를 의미한다.
session (string) [선택 인자]
세션을 통해 자동 로그인 시 사용된다.
이 경우 user_id, user_pw 는 불필요하다.
user_uuid (string) [선택 인자]
유저의 기기 FCM 토큰값을 의미한다.
해당 값을 보낼 경우 DB에 FCM 토큰 값이 갱신된다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 로그인 실패
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
session (string) [반환 보장]
추후 요청시 쓰일 본인 인증 세션 키.
로그인 시마다 갱신되며 모든 플랫폼에서 공유된다.
단, user_block 값이 0보다 클 경우 빈 값이 반환된다.
user_index (int) [로그인 성공 시 반환 보장]
유저를 식별하는 데 쓰이는 index key.
user_id (string) [로그인 성공 시 반환 보장]
유저가 로그인한 아이디.
user_level (int) [로그인 성공 시 반환 보장]
유저의 계정 등급을 의미한다.
0 : 일반 사용자
1 : 관리자
2 : 최고 관리자
user_name (string) [로그인 성공 시 반환 보장]
유저의 이름을 의미한다.
user_sid (string) [NULL 가능성 있음]
유저의 학번을 의미한다.
user_block (int) [NULL 가능성 있음]
유저의 계정 로그인 금지 일수를 의미한다.
이 값이 NULL아니고 0보다 클 경우 로그인 불가 처리하여야 한다.
또한 이 경우 session은 빈 값이 반환된다.
user_group_index (int) [로그인 성공 시 반환 보장]
유저가 속한 그룹의 인덱스.
user_group_name (string) [로그인 성공 시 반환 보장]
유저가 속한 그룹의 그룹명.
필수로 반환되지만, 관리자가 해당 그룹을 삭제하였다면 이름이 없기에 공란이다.
user_email (string) [NULL 가능성 있음]
유저의 이메일을 의미한다.
user_phone (string) [NULL 가능성 있음]
유저의 휴대전화 번호를 의미한다.
user_created (string) [로그인 성공 시 반환 보장]
유저가 등록된 시각을 의미한다.
형식은 yyyy-MM-dd HH:mm:ss이다.
로그인 방식이 user_id+user_pw , session 두 종류임에 유의.
다만 추후 논의 후 간소화 여지 있음.
로그아웃을 담당하는 API
관리자의 시스템 로그아웃
일반 사용자의 시스템 로그아웃
session (string) [필수 인자]
로그아웃할 세션을 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 로그아웃 실패
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
없음.
유저 추가를 담당하는 API
일반 유저의 신규 회원가입
관리자의 신규 유저 생성
session (string) [반 필수 인자]
세션 값이 없을 경우, 주어진 정보로 일반 사용자 회원가입만 가능하다.
세션 유저의 등급이 관리자 이상이어야 관리자 이상 사용자 생성이 가능하다.
user_id (string) [필수 인자]
유저의 아이디를 의미한다.
user_pw (string) [필수 인자]
유저의 비밀번호를 의미한다.
서버에서 bcrypt 알고리즘을 통해 암호화하여 저장한다.
user_level (int) [필수 인자]
유저의 계정 등급을 의미한다.
0 : 일반 사용자
1 : 관리자
2 : 최고 관리자
user_name (string) [필수 인자]
유저명을 의미한다.
user_group (int) [선택 인자]
유저가 속할 그룹을 의미한다.
전달받은 인자가 없을 경우 0번 그룹에 기본으로 속한다.
user_sid (string) [선택 인자]
유저의 학번을 의미한다.
user_block (int) [선택 인자]
유저의 남은 정지 일수를 의미한다.
user_uuid (string) [선택 인자]
유저의 스마트폰 FCM 토큰 값을 의미한다.
user_email (string) [선택 인자]
유저의 이메일을 의미한다.
user_phone (string) [선택 인자]
유저의 휴대기기 번호를 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 생성 실패 (아이디 중복 등)
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
user_index (int) [성공 시 반환 보장]
생성된 유저의 index를 의미한다.
일반 사용자는 session 값이 없을 때, 신규 가입이 가능하다.
관리자 이상 사용자는 session 값과 함께, 자신 계정 등급 이하 계정 생성이 가능하다.
유저 정보를 수정하는 API
관리자의 회원 수정
일반 사용자의 자신 정보 수정 (계정 등급 및 그룹 수정 불가)
session (string) [필수 인자]
세션 키가 없으면 수정이 불가능하다.
세션 유저가 일반 사용자일 경우, 자기 자신에 대한 정보 수정만 가능하다.
단, 이 경우 자신 계정 등급과 그룹은 수정할 시 권한 오류가 리턴된다.
세션 유저가 관리자일 경우, 제한 없이 모두에 대한 수정이 가능하다.
user_index (int) [필수 인자]
수정할 유저의 인덱스를 의미한다.
user_id (string) [선택 인자]
수정할 유저의 아이디를 의미한다.
user_pw (string) [선택 인자]
수정할 유저의 비밀번호를 의미한다.
user_level (int) [선택 인자]
수정할 유저의 계정 등급을 의미한다.
0 : 일반 사용자
1 : 관리자
2 : 최고 관리자
user_name (string) [선택 인자]
수정할 유저의 이름을 의미한다.
user_group (int) [선택 인자]
수정할 유저가 속할 그룹을 의미한다.
user_sid (string) [선택 인자]
수정할 유저의 학번을 의미한다.
user_block (int) [선택 인자]
수정할 유저의 남은 정지 일수를 의미한다.
user_uuid (string) [선택 인자]
수정할 유저의 스마트폰 FCM 토큰 값을 의미한다.
user_email (string) [선택 인자]
수정할 유저의 이메일을 의미한다.
user_phone (string) [선택 인자]
수정할 유저의 휴대기기 번호를 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 수정 실패 (아이디 중복 등)
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
user_index (int) [성공 시 반환 보장]
수정된 유저의 index를 의미한다.
session과 user_index를 제외한 값이 모두 선택적 인자이다.
선택적 인자로 값을 받으면, 값을 받을 때마다 해당 값만 DB에서 갱신한다.
그렇기에, 수정하지 않는 기존과 동일한 다른 인자들을 서버로 보내게 되면 무의미한 부하가 생긴다.
유저를 삭제하는 API
유저 스스로의 회원 삭제
관리자의 유저 삭제 처리
session (string) [필수 인자]
세션 키가 없으면 삭제가 불가능하다.
세션 유저가 일반 사용자일 경우, 자기 자신에 대한 삭제만 가능하다.
세션 유저가 관리자일 경우, 제한 없이 모두에 대한 삭제가 가능하다.
user_index (int) [필수 인자]
삭제할 유저의 인덱스를 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 삭제 실패
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
유저 정보 목록 API
사용자가 자신의 정보를 확인
관리자가 모든 유저 리스트 확인
session (string) [필수 인자]
세션 유저가 사용자 등급일 경우 자기 자신만 조회가 가능하다.
user_index (int) [선택 인자]
검색할 유저의 인덱스를 의미한다.
만일 사용자 등급 세션으로 다른 유저 인덱스를 요청하면 거부된다.
user_group (int) [선택 인자]
검색할 유저에 그룹 필터를 적용한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 그룹 삭제 실패
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
users (JSONArray) [성공 시 반환 보장]
유저 목록을 의미한다.
아래 상세 설명 참고.
groups (JSONArray) [조건부 반환 보장]
유저 그룹 목록을 의미한다.
관리자 등급 세션에서 요청했을 때만 반환된다.
아래 상세 설명 참고.
users는 이하 값들로 이루어진 JSONObject 의 Array 이다.
user_index (int) [반환 보장]
유저의 인덱스를 의미한다.
user_id (string) [반환 보장]
유저의 아이디를 의미한다.
user_level (int) [반환 보장]
유저의 계정 등급을 의미한다.
0 : 일반 사용자
1 : 관리자
2 : 최고 관리자
user_name (string) [반환 보장]
유저의 이름을 의미한다.
user_sid (string) [NULL 가능성 있음]
유저의 학번을 의미한다.
user_block (int) [NULL 가능성 있음]
유저의 남은 정지 일수를 의미한다.
user_uuid (string) [NULL 가능성 있음]
유저의 스마트폰 FCM 토큰 값을 의미한다.
user_group_index (int) [반환 보장]
유저가 속한 그룹 인덱스를 의미한다.
user_group_name (string) [반환 보장]
유저가 속한 그룹명을 의미한다.
그룹명이 없거나 잘못된 그룹 인덱스일 시 빈값이 반환된다.
user_email (string) [NULL 가능성 있음]
유저의 이메일을 의미한다.
user_phone (string) [NULL 가능성 있음]
유저의 휴대기기 번호를 의미한다.
user_created (string) [반환 보장]
유저의 가입 시각을 의미한다.
yyyy-MM-dd HH:mm:ss 형식이다.
groups는 이하 값들로 이루어진 JSONObject 의 Array 이다.
group_index (int) [반환 보장]
유저 그룹의 인덱스를 의미한다.
group_name (string) [반환 보장]
유저 그룹의 그룹명을 의미한다.
session의 권한이 사용자일 경우 user_index가 자신이 아니면 거부됨을 유의.
유저 그룹을 추가하는 API
관리자가 유저 그룹을 추가
session (string) [필수 인자]
세션 유저가 관리자일 경우에만 유저 그룹 추가가 가능하다.
user_group_name (string) [필수 인자]
추가할 유저 그룹의 이름을 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 그룹 추가 실패 (이름 중복 등)
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
user_group_index (int) [성공 시 반환 보장]
추가된 유저 그룹의 index를 의미한다.
session 유저가 관리자가 아닐 경우 에러가 리턴된다.
유저 그룹을 수정하는 API
관리자가 유저 그룹을 수정
session (string) [필수 인자]
세션 유저가 관리자일 경우에만 유저 그룹 수정이 가능하다.
user_group_index (int) [필수 인자]
수정할 유저 그룹의 인덱스를 의미한다.
user_group_name (string) [선택 인자]
수정할 유저 그룹의 이름을 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 그룹 수정 실패 (이름 중복 등)
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
user_group_index (int) [성공 시 반환 보장]
수정된 유저 그룹의 index를 의미한다.
session 유저가 관리자가 아닐 경우 에러가 리턴된다.
session과 user_group_index를 제외한 값이 모두 선택적 인자이다.
선택적 인자로 값을 받으면, 값을 받을 때마다 해당 값만 DB에서 갱신한다.
그렇기에, 수정하지 않는 기존과 동일한 다른 인자들을 서버로 보내게 되면 무의미한 부하가 생긴다.
다만, 이 경우 선택적 인자가 user_group_name 뿐이므로 사실상 선택적인 인자가 아니다.
유저 그룹을 삭제하는 API
관리자가 유저 그룹을 삭제
session (string) [필수 인자]
세션 유저가 관리자일 경우에만 유저 그룹 삭제가 가능하다.
user_group_index (int) [필수 인자]
삭제할 유저 그룹의 인덱스를 의미한다.
result (int) [반환 보장]
처리 결과 코드를 의미한다.
0 : 성공
-1 : REQEUST 인자 에러
-2 : 서버 동작 에러
-3 : 유저 권한 없음
-4 : 유저 그룹 삭제 실패
error (string) [반환 보장]
result가 0 이 아니면 해당 원인을 알려준다.
session 유저가 관리자가 아닐 경우 에러가 리턴된다.
유저 그룹에 유저가 존재하는 데 유저 그룹을 삭제할 경우, 해당 유저들은 로그인 시 유저 그룹의 이름이 공란으로 출력된다.
삭제 시 한번 더 관리자의 확인 작업이 요구된다.