RESTful API
RESTful API는 REST의 6가지 규약을 지키며 구현한 API를 말합니다.
REST에는 명확한 구현 규약이 존재하지 않습니다. 따라서 RESTful은 REST의 비공식적인 구현 규약이라고 여길 수 있고, 개발자마다 다른 생각을 가지고 구현하게 될 수도 있습니다.
RESTful의 비공식적인 구현 규약에는 routing 규칙, return 규칙, header 규칙 등이 존재합니다.
여기서는 가장 보편적으로 고민하게될 routing 규칙에 대해서만 알아보겠습니다.
필요할경우 다양하게 찾아보면 될 듯 합니다. (마이크로소프트의 설계가이드)
RESTful API의 Routing 규칙
Routing 규칙은 보편적이며 거의 확고하게 정해진 상황입니다.
보편적으로 다음의 7가지 규칙이 존재합니다.
URI는 정보의 자원을 표시해야 하며 동사보다는 명사를, 대문자보다는 소문자를 사용해야 합니다.
Bad Example
/getAllUsers, /GetUsersById, /createUser 등
Good Example
[GET] /users, [POST] /users
URI의 마지막에 슬래시(/)를 포함하지 않아야 합니다.
Bad Example
/users/, /students/
Good Example
[GET] /users, [GET] /students
언더바 대신 하이픈을 사용해야 합니다
Bad Example
/my_date, /personal_data
Good Example
[GET] /my-date, [GET] /personal-data
파일확장자는 URI에 포함하지 않습니다
Bad Example
/users/13/photo.jpg
Good Example
[GET] /users/13/photo
리소스는 영어 복수형으로 적습니다
Bad Example
/user, /student
Good Example
[GET] /users, [GET] /students
URI에 행위를 포함하지 않고 행위는 HTTP method로 표현해야 합니다
Bad Example
/delete-post/13
Good Example
[DELETE] /post/13
참고표
CRUD HTTP Method Route 예제 resource의 목록 표시 GET /students resource 중 하나 표시 GET /students/:id resource 생성 POST /students resource 수정 PUT /students resource 삭제 DELETE /students
슬래시(/)로 계층 관계를 표현합니다
Example
[GET] /houses/apartments
RESTful API의 Routing 예시
아래와 같은 JSON 형식의 학생 resource가 존재하고, 개발자는 학생 resource를 관리한다고 가정하겠습니다.
{
"id": 1,
"firstName": "First",
"lastName": "Last",
"classes": [
{"id": 1, "name": "Korean history"},
{"id": 2, "name": "K-pop"},
{"id": 3, "name": "Food history"}
]
}학생 resource의 CRUD 라우팅 정보는 아래처럼 구성할 수 있습니다
[GET] /students
전체 student 목록 가져오기
[GET] /students/1
id가 1인 student 정보 가져오기
[GET] /students?lastName=Last
lastName이 Last인 student를 조회해옵니다
[POST] /students
새로운 student를 등록합니다
[PUT] /students/1
id가 1인 student의 정보를 수정합니다
[DELETE] /students/1
id가 1인 student의 정보를 삭제합니다
잘못된 RESTful Routing 예시
- CRUD를 GET과 POST 혹은 POST 하나로 모두 처리하고 그 구분을 URI 주소로 처리하는 경우
Routing 주소에 행위가 들어갈경우 (search 같은 특수한 상황은 예외일 수 있습니다)
[POST] /users/update -> [POST] /users/1
결론
RESTful은 REST의 비공식적인 구현 약속으로 API를 설계하는 하나의 수단일 뿐이지 반드시 이렇게 설계해야 하는 것은 아닙니다.
트위터 API도 살펴보면 전형적인 RESTful 하지 않은 API인 것을 알 수 있습니다 (전부 GET과 POST로 처리합니다).
통일성과 확장성이 RESTful의 장점이므로 따로 문제가 없을경우 상황에 맞게 적용할지 말지 고민해보면 되겠습니다.
