URI
기본구조
/api/{version}/{module}/.../...?{query-string}
- API 버전을 URL에 포함시킨다.
- 명사만 사용한다. 행위는 Method로 표현한다.
- URI는 Spinal-case, 그 밖에는 CamelCase를 사용한다.
- Path에는 복수형 명사를 사용한다.
- 리소스 간에 관계가 있는 경우 하위 리소스로 표현한다.
/api/v1/common/users
/api/v1/common/codes/{code-id}
/api/v1/person/person-classifications
/api/v1/common/pages/{page-id}/page-services
/api/v1/person/person-classifications/{person-classification-id}/sub-person-classifications
[참고] 프로그래밍 명명 규칙
개발자들은 코딩 할 때 클래스 명, 메소드 명, 함수 명, 변수 명, 테이블 명, 컬럼 명 등의 이름을 지을 때 어떤 규칙으로 이름을 명명할지 고민하는 경우가 많습니다. 이러한 개발자들의 고민을 덜어주기 위해 이미 개발자 선배님들께서 만들어 놓은 프로그래밍 명명 규칙(관례)으로 다음과 같은 종류가 있습니다.
낙타 표기법 (Camel Case)
낙타 표기법은 단봉 낙타의 혹을 연상한다는 의미로 명명되었습니다. 각 단어의 첫 문자를 대문자로 표기하되, 이름의 첫 문자는 소문자로 작성합니다. 일반적으로 변수명이나 함수명을 Camel Case로 작성합니다.
파스칼 표기법 (Pascal Case)
쌍봉 낙타 표기법이라고도 불립니다. 각 단어의 첫 문자를 대문자로 표기하며, 이름의 첫 문자 또한 대문자로 작성합니다. 일반적으로 Class명은 Pascal Case로 작성합니다.
케밥 표기법
케밥 표기법은 Spinal Case, Train Case, Lisp Case라고도 불립니다. 각 단어의 사이를 하이픈(-)로 구분해주는 표기법입니다. 일반적으로 HTML 태그의 id, class 속성으로 사용됩니다.
뱀 표기법 (Snake Case)
각 단어의 사이를 언더바(_)로 구분해주는 표기법입니다. 일반적으로 데이터베이스(DB) 테이블명이나 컬럼명을 Snake Case로 작성합니다.
Ex) snake_case, table_name, user_name
헝가리안 표기법 (Hungarian Case)
이름 앞에 변수의 타입을 접두어로 넣어주는 표기법입니다. 접두어의 종류에는 ch(char), str(string), i(int), db(double), b(boolean) 등이 있습니다.
Ex) strUserAge, iUserAge
Query Parameter
Filtering
GET /api/v1/common/codes?codeType=0
GET /api/v1/common/pages?useYn=no
Sorting
복수의 필드에 대해서 오름/내림차순 정렬을 가능하게 한다.
GET /api/v1/common/pages?sort=+module,+pageName
Paging
offset과 limit을 사용하고 Default값을 항상 사용한다.
전체 페이지 수를 제공할 경우 헤더에 정보를 제공한다.
GET /api/v1/common/codes?pageCount=50&pageNo=2
Method
GET, POST, PUT, DELETE를 사용한다.
Get method는 Server의 상태를 변경시키지 않아야 한다.
에러는 적절한 상태코드와 함께 Payload에 상세한 정보를 포함한다.
CRUD와 Method
| CRUD Action | Method | Description |
| CREATE | POST | 하위 리소스를 생성 |
| READ | GET | |
| UPDATE | PUT | 대상 Resource가 존재하지 않는 경우 : 404 Page Not Found |
| DELETE | DELETE | |
| 기타 | POST | CRUD로 표현할 수 없는 경우에만 사용 |
Non-CRUD API
- CRUD로는 표현할 수 없는 API들이 존재(RPC Style)
- 이런 API들은 POST Method를 통해 처리
File Export (Excel 등)
Batch 작업 시작
복잡한 작업 프로세스 컨트롤 (단순 상태 값 변경이 아닌 경우)
-- The End --