REST, RESTful API

REST

: REST(Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 모든 것을 의미함

 

• HTTP URI(Uniform Resoruce Identifier)를 통해 자원을 명시
• HTTP Method(POST, GET, PUT, DELETE, PATCH 등)을 사용함
• 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미
  • CRUD Operation
    • Create : 데이터 생성 (POST)
    • Read : 데이터 조회 (GET)
    • Update : 데이터 수정 (PUT, PATCH)
    • Delete : 데이터 삭제 (DELETE)

REST 구성 요소

• 자원 (Resource) : HTTP URI
• 자원에 대한 행위 (Verb) : HTTP Method
• 자원에 대한 행위의 내용 (Representations) : HTTP Message Pay Load

REST의 특징

• CS구조 (Client-Server 구조)
• Stateless (무상태)
• Cacheable (캐시 처리 가능)
• Layered System (계층화)
• Uniform Interface (인터페이스 일관성)

REST의 장단점

• 장점
  • HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API의 사용을 위한 별도의 인프라를 구축할 필요가 없음
  • HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해줌
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능함
  • Hypermedia API의 기본을 충실히 지키면서 범용성을 보장함
  • REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있음
  • 여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화함
  • 서버와 클라이언트의 역할을 명확하게 분리함
• 단점
  • 표준 자체가 존재하지 않아 정의가 필요함
  • HTTP Method 형태가 제한적
  • 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구됨
  • 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많음

REST API 

: REST API란 REST의 원리를 따른 API를 뜻함

• RESTful API : REST API의 하위 개념으로 REST API가 지향하고자 하는 설계 규칙을 따른 API를 뜻함

1. URL 룰 : 계층 표현은 슬래시로 표현하되 마지막에는 슬래시를 사욯하지 않음

NG	G
http://example/create/1/	http://example/create/1

 

2. 언더바 (_) 대신 대시 (-)를 사용

NG	G
POST http://example.com/create-role	POST http://example.com/roles

 

3. 소문자 사용 : 일관된 URI를 사용하여 가독성과 단순함을 지향, API 설계는 일관성이 핵심이므로 직관적이지 않은 부분을 최소화하고 유지보수성을 극대화하기 위하여 일관된 리소스 명명 규칙과 URI 형식을 사용

 

4. 단순하고 간단한 구조로 작성 : WEB API 디자인하는데 있어서 한 리소스에 대해서는 단 두 개의 접근 URL을 제공해야 함. 같은 주소를 호출하면 같은 데이터 출력을 보장해야 하고 이를 멱등성 보장이라고 함

복수 (Collection)	단수 (Document or Element)
/a1/roles	/a1/roles/1

 

5. URL에 HTTP메서드를 노출하지 않아야 함 : 파일 확장자를 URI에 사용하지 않고 API의 URI를 표현하기 위해서 동사나 동사구를 사용하지 말고 명사를 사용하여 리소스 표현

NG	G
POST http://example.com/create-role	POST http://example.com/roles

 

6. Resource URI에 항목/컬렉션보다 더 깊은 depth를 가져가지 않도록 함 : 불가피한 경우 최대 4depth를 허용하되 직관적이고 단순한 형태의 URI를 사용

 

7. 의미에 맞는 HTTP 상태를 반환 : HTTP 반환 Stats는 정상 (200)인데 시스템 내부의 사용자 정의 코드 및 메시지가 에러를 리턴하는 형태로 표현되면 안됨 즉, HTTP <-> System Sync가 맞아야 함

 

8. API 버전 명시 : 가급적 상위 버전은 하위 버전의 하위 호환성을 유지, API는 언제든 수정사항이 발생할 수 있으며 리소스의 관계가 바뀌거나 데이터 구조가 수정되는 일이 번번하기 때문에 해당 API가 변경됨에 따라 클라이언트 측에 미치는 영향을 고려해야 함

NG	G
/roles	/v1/roles

 

9. 리소스에 대한 정렬, 필드에 대한 필터, 페이징은 쿼리 파라미터를 활용 : 별도의 API를 만들기 보다 쿼리 파라미터를 활용하여 담는게 좋음

부분 응답	페이징 처리
/request?fields=info.person.name	/request?offest=0&limit=10

 

10. 문서로 자세히 정리되어 있어야 함 : 단순 스펙에 대한 문서 제공뿐만 아니라 실행 가능한 mock 데이터들은 API 실행 테스트 환경에서 확인할 수 있어야 함, 자바에서는 스웨거나 Rest Docs와 같은 API 문서화 라이브러리를 주로 이용함

 

이를 통해 API를 연동하는 파트너나 고객, 개발 관련 부서와의 커뮤니케이션이 줄어들게 됨, 같은 프로젝트에서 소속된 기획 부서나 현업 담당자들도 API 문서 코드를 보고 테스트해볼 수 있도록 환경을 쉽게 제공해야 함