Web API
API란?
Application Programming Interface의 약자로, 개발할 때 사용할 수 있도록 특정 라이브러리나 플랫폼 등이 제공하는 데이터나 함수 등을 의미한다
-
웹 개발 시, 어느 URL로 request를 보냈을 때 무슨 처리가 수행되고 어떤 리스폰스가 오는지에 관해 미리 정해진 규격을 Web API라고 한다
-
즉, Web API를 설계한다는 것은 서비스에서 사용될 모든 URL들을 나열하고, 각각의 URL에 관한 예상 request와 response의 내용을 정리한다는 뜻이다
REST API란?
REST는 Representational State Transfer의 줄임말로, REST API는 Web API 설계의 가이드라인이다
- Web API를 설계하는 데에는 여러 방식이 적용될 수 있는데, 잘 설계하기 위한 기준으로 REST API의 6가지 조건(REST architecture)을 만족해야 한다
REST architecture?
- Roy Fielding이 본인의 논문 'Architectural Styles and the Design of Network-based Software Architectures'에서 제시한 개념이다
- 그는 웹이 갖추어야 할 이상적인 구조(architecture)로 REST architecture 개념을 제시했다
REST architecture에는 6가지 조건이 있다
1. Client-Server
- Client-Server 구조를 통해 양측의 관심사를 분리해야 한다
- 분리를 통해 Client 측은 사용자에게 더 좋은 화면을 보여주는 방법, 다양한 기기에 대처하는 방법에 집중할 수 있고, Server 측은 서비스에 적합한 구조, 확장 가능한 구조를 어떻게 구축할 것인지에 대해 집중할 수 있다
- 이로써 각자 독립적으로 운영될 수 있게끔 한다
2. Stateless
- Client가 보낸 각 request에 관해서 Server는 그 어떤 맥락(context)도 저장하지 않는다
- 즉, 매 request는 각각 독립적인 것으로 취급되기에 request는 항상 필요한 모든 정보가 담겨야한다
3. Cache
- Server는 response에 Client가 response를 재활용해도 되는지의 여부를 담아서 보내야한다
- 이를 통해 네트워크 비용을 절감할 수 있다
4. Uniform Interface
- Uniform Interface는 하위 조건 4가지를 준수해야 한다
이 조건들은 REST API와 연관이 깊다
4-1) Identification of Resources
- 리소스를 URI(Uniform Resource Identifier)로 식별할 수 있어야 한다
4-2) Manipulation of Resources through Representations
- Client와 Server는 리소스를 직접적으로 다루는 게 아니라, 리소스의 표현(representations)을 다뤄야 한다
- REST architecture은 '리소스'와 '리소스의 표현'을 엄격하게 구분한다
4-3) Self-Descriptive Messages
- '자기설명적인'이라는 뜻으로, Stateless 조건으로 인해 매 Request마다 필요한 모든 정보를 담아서 전송해야 한다
- Client의 request, Server의 response 모두 그 자체의 정보만으로 모든 것을 해석할 수 있어야 한다
4-4) Hypermedia as The Engine of Application State
- Hypermedia는 Hypertext처럼 문서뿐만 아니라 이미지, 소리, 영상까지도 포괄하는 개념이다
- 이 조건은 Server의 response에는 현재 상태에서 다른 상태로 이전할 수 있는 링크를 포함하고 있어야 한다는 조건이다
5. Layered System
- Client와 Server 사이에는 Proxy, Gateway와 같은 중간 매채 요소를 두고, 보안, 로드 밸런싱 등을 수행할 수 있어야 한다
- 이를 통해 Client와 Server 사이에 계층형 층(Hierarchical layers)들이 형성된다
6. Code-On-Demand
- Client는 받아서 바로 실행할 수 있는 applet이나 script 파일을 Server로부터 받을 수 있어야 한다
- 이 조건은 REST architecture에 있어서 선택적인 조건이다
개발자들이 강조하는 규칙들
- 구체적으로 어떻게 설계해야 REST API가 될 수 있는 걸까?
- 많은 개발자들의 경험과 논의를 통해 사실상의 규칙들이 형성되었다
1) URL은 리소스를 나타내기 위해서만 사용하고, 리소스에 대한 처리는 메소드로 표현해야 한다
즉, URL에서 리소스에 대한 처리를 드러내면 안 된다는 규칙이다
ex) 규칙을 지킨 경우
(1) 'https://learn.codeit.kr/api/members' URL로
(2) 리퀘스트의 헤드에 POST 메소드를 설정하고,
(3) 리퀘스트의 바디에 새 직원 정보를 넣어서 보낸다
ex) 규칙을 어긴 경우
(1) 'https://learn.codeit.kr/api/members/add' URL로
(2) 리퀘스트의 헤더에 GET 메소드를 설정하고,
(3) 리퀘스트의 바디에 새 직원 정보를 넣어서 보낸다
규칙을 어긴 경우, URL에서 리소스에 대한 처리(add)까지 나타내고, 메소드 값은 리소스 처리가 아닌 조회(GET)를 설정했기에 규칙을 어긴 것이다
2) 도큐먼트는 단수 명사로, 컬렉션은 복수 명사로 표시합니다
- 도큐먼트(document)는 파일들을 담을 수 있는 디렉토리, 컬렉션(collection)은 하나의 파일에 해당하는 개념이다
ex) 'https://www.soccer.com/europe/teams/manchester-united/players/pogba' 의 URL에서 도큐먼트와 컬렉션은?
- 도큐먼트 : europe, manchester-united, pogba
- 컬렉션 : teams, players
위의 'https://learn.codeit.kr/api/members' URL에서 직원 전체에 해당하는 컬렉션인 members는 복수 명사로 표현했다
| 제목 | /members | members/3 |
|---|---|---|
| GET | 전체 직원 정보 조회 | 3번 직원 정보 조회 |
| POST | 새 직원 정보 추가 | X |
| PUT | 전체 직원 정보 수정(잘 쓰이지 않음) | 3번 직원 정보 갱신 |
| DELETE | 전체 직원 정보 삭제(잘 쓰이지 않음) | 3번 직원 정보 삭제 |
이외에도 여러 조건들이 있으니 더 찾아보자!
