📌 REST API란?
<aside>
💡 사람들이 'REST API'라는 용어를 사용할 때 일반적으로 사전 정의된 URL 집합을 HTTP 프로토콜을 사용하여 API를 접근하는 것을 뜻합니다.
출처: How to Use Our REST APIs
</aside>
- 깨알지식
- 실제 REST는 하이퍼미디어에 기반한 분산 시스템을 만들기 위한 아키텍쳐 스타일. 고로 HTTP에 꼭 연관 되어 있지 않아도 됨.
- 하지만 대부분 REST API는 HTTP protocol를 사용함.
- 역사
- REST 이전엔 SOAP을 사용함.
- 2000년도 “로이 필딩”이 박사 논문으로 “Architectural Styles andthe Design of Network-based Software Architectures” 발표함. 챕터 5에 REST 제약조건을 서술. 어떤 서버이든 아무 서버와 통신할 수 있도록 가능케 해주는 아키텍쳐.
- 2000년 Salesforce라는 “Internet as a Service” 제품에 처음 도입함. 당시에는 XML기반으로 사용함.
- 그 다음 eBay가 도입함. eBay가 도입 당시 자신들의 API를 접속할 수 있는 모든 웹사이트를 대상으로 시장을 확대함.
- eBay로 인해 Amazon이 2002년도에 도입함.
- Flickr가 2004년도 도입. REST API를 도입함으로써 블로거들이 자신들의 사이트에 쉽게 이미지를 embed 할 수 있도록 함.
- 2006년 AWS가 AWS REST API를 도입하여 개발자들이 데이터 공간을 수분 내에 접근할 수 있도록 함.
- 오늘날 REST API는 인터넷의 근간이 되었음.
- 참고:
- REST의 장점
- JSON/XML/HTML의 형식이면서, 경량, lightweight임.
- 클라이언트와 서버의 독립
- 확장성과 유연성
- 서버/클라이언트의 독립으로 인해 확장이 용이함.
- 개발자들은 추가 수고 없이 REST API를 자신들의 소프트웨어 도입할 수 있음.
- 참고:
- SOAP vs REST
- SOAP은 표준화 된 프로토콜
- REST는 아키텍쳐 스타일
📌 REST API 설계 방법
-
리소스 중심으로 설계. 웹 API가 노출하는 비즈니스 엔티티에 집중
-
리소스는 명사 중심, 동사 지양 (가능하면)
-
구조는 collection/item/collection
/customers/1/orders- 이 계층 이상으로 넘어가는 것 지양.
/customers/1/orders/99 까지는 괜찮지 않을까 개인적으로 생각./customers/1/orders/99/products 이런 쿼리는
/customers/1/orders/orders/99/products- 이렇게 나눠서 쿼리
-
내부 데이터베이스 구조를 그대로 API에 노출 지양
-
여러 리소스를 여러 request에 나누기 보다는 한번에 불러 올 수 있도록 설계. 단, overfetching은 피하기.
-
만약, API operation을 특정 리소스에 맵핑 할 수 없다면 query string 사용.
- 예) GET 요청 /add?operand1=99&operand2=1
-
Media types
출처: Web API design best practices - Azure Architecture Center
일반적인 CRUD 형태
- HTTP Method 요청
- PUT vs PATCH
- PUT:
- item에 대한 전체 업데이트.
- idempotent (멱등성: 연산을 여러번 적용하더라도 결과가 달라지지 않음.)
- PATCH:
- item에 대한 부분 업데이트. * PATCH도 item에 대한 전체 업데이트 가능.
- idempotent (멱등성 보장하지 않음.)
출처:Web API design best practices - Azure Architecture Center