REST API
。HTTP를 기반으로 하여REST 제약조건을 준수하는API
▶클라이언트와Web Application간데이터를 주고받기위한인터페이스
。언어 , 프레임워크 , 기술등에 영향을 받지 않으면서 지정된데이터 형식(JSON,XML)을 통해클라이언트와서버간 데이터 교환이 가능
。HTTP Method를 지원 및HTTP의STATELESS특징을 승계하여서버는클라이언트를 알 수 없다.
▶ 매Request마다인증을 요구.
▶GET, POST, DELETE, PUT, HEAD, PATCH, OPTIONS를 지원
。Spring의REST API는Spring MVC에서@RestController를 통해Controller로서 구축되어요청및응답이 수행
▶@ResponseBody기능 추가
REST Architecture제약 조건
。HTTP만 잘 지키더라도Client-Server,Stateless,Cache,Layered System을 모두 준수
▶HTTP 프로토콜을 사용하는 상태에서REST API 설계시Uniform Inteface만 중점적으로 고려
Client-Server
。HTTP 프로토콜을 사용하는구조자체가Client - Server Architecture이므로 준수
Stateless
。HTTP 프로토콜은STATELESS특징으로서버에서클라이언트에 대한 정보를 알 수 없으므로 준수
Cache
。HTTP는Web Cache를 사용
Layered System
。HTTP는클라이언트와서버사이에프록시서버(웹캐시) ,API 게이트웨이등 다양한중간 계층들 간에 서로기능별로 독립되어 분리
▶계층의유지보수시 다른계층에 영향을 주지않음.
▶클라이언트는서버와 통신 시 어떤중간 계층을 거치는지 알 수 없음
Code-on-Demand( Optional )
。Code-on-Demand는서버에서코드를클라이언트로 전송하여 실행할 수 있도록 한다.
▶ 이는JS를 의미하며 꼭 준수할 필요는 없음.
Uniform Interface
。클라이언트가서버내자원에 접근하는 방식이 일관되도록 하도록 하는 것
▶REST API 설계시 가장 신경쓸 부분
Uniform Interface
。클라이언트가서버내자원에 접근하는 방식이 일관되도록 하도록 하는 것
▶서버내 다른자원에 접근하더라도 항상 동일한Type(Http Method,URI 구조,Response Format)으로 접근이 가능하도록 하는 것
Identification of Resource
。서버내 모든자원은 고유한URL로 식별되어야함
▶ 명확한비즈니스 모델로 설정
ex )/users/1,/orders/2, ...
Manipulation of resources through representations
。클라이언트에서Representation(JSON,XML, ... )를 전송하여서버 내 자원의 조작(CRUD)이 가능한 것
Self-Descriptive Message
。API의요청과응답은외부 문서없이 스스로 설명할 수 있어야한다.
▶HTTP Message에 표현을 작성하여추가 문서없이HTTP Message자체만으로 의미를 이해해야할 수 있어야하는 능력
Self Descriptive한HTTP Message예시POST /api/index.html HTTP/1.1 Host: example.com Content-Type: application/json-patch+json // Data type 지정 Content-Length: 45 { // Http Message Body 부분 "name": "홍길동", "email": "hong@example.com" }。
목적지 Host:example.com
。요청할 서버내 자원:/api/index.html
。Content-Type 헤더:application/json-patch+json
▶json-patch 명세를 통해HTTP Message Body의변수를 설명
▶ 다음처럼 작성하여메시지 내용으로 온전히 해당메시지를 해석 할 수 있어야한다.
HATEOAS
。REST API는Hypertext-driven되어야한다.
。클라이언트에서REST API를 통해 제공된 다른자원을 지시하는하이퍼링크를 통해어플리케이션의상태를전이
▶Http Message의Link 헤더를 통해 다른자원에 대한하이퍼링크를 제공HTTP/1.1 200 OK Content-Type: application/json Link: </articles/1>; rel="previous", </articles/3>; rel="next";
REST API설계
REST API는Hypertext-driven되어야한다
。API에HATEOAS적용
▶클라이언트에서Hyperlink를 통해어플리케이션의상태를 변화
Resource의명사표현 :
。URL은Resource이므로도메인( =비즈니스 모델)으로 지칭하며동사가 아닌명사들로 구성되어야 한다.
▶REST API설계 시단수,복수형을 섞어 사용하지 않으며, 모든Resource에 대해복수형 명사사용!
자원검색 시Path Variable사용 :
。Query String의/getUser?id=1이 아닌@RestController에 의한Path Variable의/users/{id}가 맞는 표현.
▶ 해당자원에 대해추가 질의가 존재하는 경우에만query string을 사용
ex )URI:https://{serviceRoot}/{collection}/{id}
- 적절한
Http Status Code를 반환
。@ResponseStatus 어노테이션을 통해클라이언트가 요청 후 성공 시200을 반환하도록@ResponseBody( code=HttpStatus.OK )설정
HTTP Method의 적절한 사용 :
。REST는 해당요청의 의도를 쉽게 파악 할 수 있도록HTTP Method를 목적에 따라 구분하여 사용.
▶POST /users/1/delete가 아닌DELETE /users/1로 표기.
HTTP Method별Endpoint
。특정Resource를 조작하기 위한URL 패턴
。users는백엔드기준도메인( =비즈니스 모델)인user에서복수로 표현가능하므로 관례적으로users로 설정
。GET /api/users: 모든 사용자 조회
。GET /api/users/{id}: 특정 사용자 조회
。POST /api/users: 새로운 사용자 생성
。PUT /api/users/{id}: 특정 사용자 정보 전체 수정
。PATCH /api/users/{id}: 특정 사용자 정보 일부 수정
。DELETE /api/users/{id}: 특정 사용자 삭제
。GET /api/users/{id}/posts: 특정 사용자와 연결된 모든 게시물 검색
。POST /api/users/{id}/posts: 특정 사용자와 연결된 게시물 생성
。GET /api/users/{id}/posts/{post_id}: 특정 사용자와 연결된 특정 게시물 검색
