REST API?
- HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.
- 즉, REST는 자원 기반의 구조(ROA, Resource Oriented Architecture) 설계의 중심에 Resource가 있고 HTTP Method를 통해 Resource를 처리하도록 설계된 아키텍쳐를 의미한다.
- 웹 사이트의 이미지, 텍스트, DB 내용 등의 모든 자원에 고유한 ID인 HTTP URI를 부여한다.
- CRUD Operation
Create : 생성(POST)
Read : 조회(GET)
Update : 수정(PUT)
Delete : 삭제(DELETE)
HEAD: header 정보 조회(HEAD)
리소스를 표현하기 위해 명사를 사용하라
RESTful URI이 가르키는 resource(or representation)는 수행되는 행위가 아니라 객체다.
이 resource (or representation)를 네 가지 범주로 나누어보겠다.
항상 리소스가 어느 범주에 해당하는 지 확인하고, 그 범주에 맞는 네이밍 컨벤션을 일관되게 사용하라.
문서(Document)
- 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
- 단수 사용 (/device-management, /user-management)
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin컬렉션(Collection)
- 서버가 관리하는 리소스 디렉터리
- 서버가 리소스의 URI를 생성하고 관리
- 복수를 사용하라
- POST 기반 등록
- 예) 회원 관리 API
- 복수 사용 (/users)
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}스토어(Store)
- 클라이언트가 관리하는 자원 저장소
- 클라이언트가 리소스의 URI를 알고 관리
- PUT 기반 등록
- 예) 정적 컨텐츠 관리, 원격 파일 관리
- 복수 사용 (/files)
http://api.example.com/files
http://api.example.com/files/new_file.txt컨트롤 URI 혹은 컨트롤러(Controller)
- 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
- 동사를 직접 사용
- 예) GET, POST만 사용할 수 있는 HTTP FORM의 경우 컨트롤 URI(동사로 된 리소스 경로)를 사용 ex) /members/delete, /members/new 등
- 동사 사용 (/checkout, /play 등)
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play일관성이 핵심이다
- 계층 관계 표현을 위해
/를 사용하라 - 마지막 문자로
/를 사용하지 마라 - 가독성을 위해
-(하이픈)을 사용하라 _(언더스코어)는 사용하지 마라- 소문자를 사용하라
- 파일 확장자를 사용하지 마라
CRUD 함수명을 사용하지 마라
- URI는 어떤 동작이 수행되는 지 가르키는 게 아니라, 리소스를 가르키는 것이다.
- 리소스에 대한 작업은 HTTP Method를 이용하도록 한다.
HTTP GET http://api.example.com/device-management/managed-devices //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices //Create new Device
HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given IdPath Variable과 Query Parameter는 언제 사용하는 걸까
Path Variable
/users/123 Query Parameter
/users?id=123- 어떤 resource를 식별하고 싶은면 Path Variable을 사용하고, 정렬이나 필터링을 한다면 Query Parameter을 사용한다.
/users # 사용자 목록을 가져온다.
/users?occupation=programer # 프로그래머인 사용자 목록을 가져온다.
/users/123 # 아이디가 123인 사용자를 가져온다.- 기본적인 CRUD 기능을 위해서 또 다른 URL이나 query parameter를 정의할 필요는 없다. 대신 원하는 기능에 맞게 HTTP 메소드를 바꾸어야 한다.
/users [GET] # 사용자 목록을 가져온다.
/users [POST] # 새로운 사용자를 생성한다.
/users/123 [PUT] # 사용자를 갱신한다.
/users/123 [DELETE] # 사용자를 삭제한다.References
기록을 통한 성장을