전공자로써 API라는 용어를 수도 없이 들었다. 심지어 졸업작품으로 진행했던 프로젝트에서 Google cloud vision API 를 가져다 썼었지만 정작 정확한 의미는 모르고 있었다.
API가 도대체 뭔데?
위키백과에서는 API를 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스 라고 정의한다. 그렇게 와닿는 말은 아닌 것 같다. 이해하기 쉽도록 예시를 준비해봤다.
매개체
Application Programming Interface 에서 interface라는 단어에 초점을 맞춰보자. 직역하면 서로 맞대는 면 정도로 해석할 수 있다.
사용자가 스마트폰 사용하는 모습을 상상해보자. 홈 화면을 보기 위해서는 전원 버튼을 눌러야 하고, 우리는 이 사실을 알고 있다. 여기서 전원 버튼이 바로 API이다. 사용자 입장에서 어떻게 스마트폰이 홈 화면을 보여줄 수 있는지에 대한 내부 로직은 전혀 몰라도 된다. 단지 사용자가 원하는 것을 제공해주는 매개체 역할을 한다.
API 명세서
그렇다면 API 명세서란 뭘까? 레스토랑에 가서 주문한다고 가정해보자. 종업원에게 메뉴판을 받아 메뉴를 고를 것이다. 메뉴판에는 사장님이 정한 규칙 하에 여러 메뉴들이 있다. 이 메뉴판을 API 명세서에, 메뉴를 API에 비유해보면 이해하기 수월하다.
단순히 여러 API를 나열하기 위해서 API 명세서를 작성하는 것이 아니다. 그 속에는 나름대로의 규칙이 있으며 궁극적으로 API 명세서를 통해 클라이언트와 서버가 소통할 수 있다.
REST API
REST는 REpresentational State Transfer 의 약자로 HTTP 기반으로 필요한 자원에 접근하는 방식을 정해놓은 규칙을 뜻한다. REST에는 아래와 같은 4개의 속성이 존재한다.
- 서버에 있는 모든 리소스는 클라이언트가 바로 접근할 수 있는 고유
URI가 존재한다. URI는 Uniform Resource Identifier 의 약자로 자원의 위치를 나타내는 일종의 식별자이다. - 클라이언트가 요청할 때마다 필요한 정보를 주기 때문에 서버에서는 세션 정보를 포관할 필요가 없다.
- GET / POST / PUT / DELETE 등의
HTTP method를 사용한다. - 서비스 내 하나의 리소스가 주변에 연관된 리소스들과 연결되어 표현되어야 한다.
그리고 REST는 resource / method / message 세 가지로 구성되어 있다.
Resource
위에서 언급했듯이 REST에서는 URI로 자원에 접근하기 때문에 URI 설계 시 지켜야 하는 규칙이 있다.
/는 계층 관계를 나타내는 데 사용되며 마지막 문자로는 사용하지 않는다./users/sangmin/ (x)- URI를 구성하는 리소스들은 명사로 이루어져야하며 소문자로 작성한다.
/users/sangmin - URI에서는
_(언더바)보다-(하이픈)을 권장한다./users/{user-idx} - 파일 확장자는 URI에 포함시키지 않는다.
/users/sangmin/logo.png (x)
Method
위에서 잠깐 언급한 HTTP method에 대해서 알아보자. 서버 측 자원에 대한 행위라는 것을 꼭 기억해야 한다.
- GET : 조회
- POST : 생성
- PUT : 수정
- PATCH : 일부 수정
- DELETE : 삭제
GET과 POST 방식의 차이점을 보안이라는 측면에서 설명하는 사람들이 많다. 나도 여태껏 이렇게 생각해왔는데, 이는 정확한 답변이 아니라고 한다.
클라이언트는 GET으로 요청할 때 querystring을 이용한다. 반면 POST 같은 경우 packet body 부분에 넣어서 보낸다. 대부분 이러한 이유 때문에 GET 방식이 POST 방식보다 보안에 취약하다고 생각할 것이다. 하지만 POST 방식으로 요청할 때도 마음만 먹으면 손쉽게 데이터를 가로챌 수 있다.
그러므로 보안성보다는 행위 자체에 초점을 두어야 한다. GET은 저장되어 있는 리소스를 조회하는 것이고, POST는 클라이언트에서 준 데이터를 새롭게 저장해달라는 요청이다.
Message
클라이언트에서 서버로 요청할 때나 서버에서 클라이언트로 응답할 때 HTTP packet(혹은 message)을 사용한다. 택배 상자를 떠올리면 더 쉽게 이해할 수 있다. 표면에 송장(Header)이 붙어 있고 안에 내용물(Body)을 담는다. Header에는 내용 타입이나 언제 보냈는지에 대한 정보, 인증 토큰처럼 metadata가 들어있으며 Body는 말 그대로 진짜 데이터를 포함한다. 추가적으로 상태 코드에 대한 내용은 Mozilla에 자세히 나와 있다.