기획자인 내가 아직까지 API가 헷갈렸던 이유 - 이론
안 해봤으니까! 개념 정리부터 API 호출까지 쉽게 도전해보자!
가깝고도 먼 그대, API
"OO님, Post 방법으로 요청할 때 query를 붙여서 호출하는 건 되도록 지양해야 해서, body로 넘겨주실 수 있나요?"
"API 호출해보니까 500번대 에러가 나고 있는 것 같아요."
기획자와 여러 개발자가 함께 일하고 있으면, 가끔 개발자들만의 언어로 대화하고 있는 것을 지켜볼 때가 왕왕 있다. 그럴 때 단골로 등장하는 단어가 바로 'API'다. 오늘은 기획자의 눈높이에서 API 개념을 정리해볼 예정이다.
뿐만 아니라 Postman을 통해 API를 직접 호출해보며 공부해볼 수 있도록 준비했다. (매우 쉬우니 겁 노노~) 필자는 이렇게 공부하고 나서 이전에 API 관련 개발자 간 메시지를 다시 살펴봤는데, 약 80%를 알아들을 수 있다는 사실에 매우 성취감을 느꼈다.
기획자의 시선에서 본 API
API(Application Programming Interface)의 사전적 의미는, 응용 프로그램에서 사용할 수 있도록 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻한다.
사전적 의미는 늘 이해하기 어려움쉽게 말하면 API는 클라이언트, 서버와 같은 서로 다른 프로그램에서 요청과 응답을 주고받을 수 있는 체계, 약속이라고 할 수 있다. API를 이용하면 한쪽의 서버가 다른 쪽의 서버에서 이미지를 받아오거나, 구성원을 로그인시켜주는 것, 메시지, 동영상 등의 데이터를 삭제하는 등의 요청이 가능하다.
또, 네이버 지도 API와 같이 다른 회사가 만들어둔 API를 가져다가 우리 제품을 구현할 수도 있다. 이렇게 다른 회사 개발자도 사용할 수 있도록 공개된 API를 Open API라고 한다.
단 조건이 있다. API를 사용할 때에는 미리 정해놓은 약속을 지켜서 서버에 요청을 해야 한다. API에는 항상 '요청'에 대한 '응답'이 있고, 정해진 방식으로 요청과 응답을 보내주도록 '체계'가 있기 때문에 미리 약속해둔 방법을 사용해야만 응답을 받을 수 있다. 여러 가지 약속들 중 우리가 꼭 알아야 하는 약속들을 살펴보자.
1. [요청할 때 약속] API URL
API를 통해 응답을 받고 싶은 서버는 누구에게 어떤 요청을 할 것인지 명시해야 한다. 이때 API URL을 사용하는데, API URL에는 서버 주소와 요청하고자 하는 API 기능이 '서버 주소/기능 이름'으로 적혀있다.
2. [요청할 때 약속]메소드: 요청의 종류
어떤 종류의 요청인지 명시해야 한다. 요청에는 4가지가 있고 흔히 CRUD라고 불린다. 이 요청 종류를 '메소드'라고 한다. '이 API 메소드가 뭐죠?'라는 질문에 해당 API가 쓰는 요청 방식이 Create라면 'Create'입니다.'라고 답하면 된다.
Create (또는 POST): 서버에 데이터를 생성하도록 하는 요청이다. Create 요청을 이용하면 A 클라이언트가 가진 정보를 B 서버에 업로드할 수 있다.
Read (또는 GET) : 서버에 있는 데이터를 불러오는 요청이다. Read 요청을 이용하면 B 서버에 있는 정보를 클라이언트 A가 가져올 수 있다.
Update (PUT/PATCH): 데이터를 바꾸는 요청이다. Update 요청을 이용하면 B서버에 있는 정보를 클라이언트 A가 원하는 다른 정보로 변경할 수 있다.
Delete: 데이터를 삭제하는 요청이다. Delete 요청을 이용해 B 서버에 있는 정보를 지울 수 있다.
괄호 안의 용어는 RESTful API일 때 사용하는 용어로, 개발 세계에서는 괄호 안 용어로 더 많이 불린다.
3. [요청할 때 약속] 헤더와 바디, 그리고 파라미터
우리가 이메일로 무언가를 요청할 때를 생각해보자.
'안녕하세요, 기획팀 OOO입니다. OOO 요청하고자 메일 드립니다.'...
일단 처음에 내가 누구고 어떤 목적으로 요청을 드리는지 설명하지 않나? API로 요청할 때에도 이렇게 내가 누구인지 등의 정보를 적는 헤더가 있고, 뭐에 대한 응답을 요청하는지를 적는 바디가 있다.
메일 쓸 때마다 처음에 어떻게 시작할지 고민,,그리고 요청할 때마다 달라지는 변수가 있다. 예를 들면 ID/PW의 경우 서로 다른 구성원들이 로그인할 때마다 다른 정보를 입력할 것이다. 이렇게 요청마다 값이 달라지는 항목을 '파라미터'라고 한다. '비밀번호'라는 항목은 '파라미터', 그리고 각 구성원들의 비밀번호 값은 'value'라고 부를 수 있다.
4. [응답할 때 약속] 응답의 명시화
API는 일종의 체계이자, 약속이기 때문에 응답도 미리 정해진 방식이 있다. 이건 개발자가 정의하는 부분이기 때문에 각 API마다 다르다. 하지만 한 가지 공통점은 API 개발 시 요청에 성공했을 때 응답과, 실패했을 때 응답을 나누어 명시화 한다는 부분이다. 그래서 API를 가져다 사용하는 개발자는, API를 개발한 개발자가 정한 응답 형식을 참고해 개발할 수 있다.
당신은 지금 이걸 어떻게 기억하냐며 절망했을 수도 있다.
아니 이걸 어떻게 다 기억해요ㅠㅠ괜찮다. 이걸 외울 필요는 정말 없고, 개념을 이해하기만 하면 된다. 왜냐하면,,, 지금 내가 말해준 내용들은 개발자가 API를 개발할 때마다 함께 작성하는 API 문서에 잘 정리해두기 때문이다. 즉, 우리는 요 개념들을 이해하기만 하면, API 문서를 보고 대충 어떻게 굴러가는지 알아낼 수 있는 경지에 오른 것이다!
특히 나는 직접 API를 시험 삼아 호출해보니까 바로 이해가 되어버렸다... 역시 해보고 체화하는 게 가장 좋은 학습 방법인가 보다. 간단한 API를 호출하는 건 정말 어렵지 않으므로, 시간이 있다면 꼭 한번 따라 해 보길 추천한다. 몇 개월째 외울 수 없었던 개념을 한 번에 머릿속에 집어넣을 수 있게 된다.
다음 편에서 API를 호출해보고 절대 까먹지 않을 수 있도록 머릿속에 저장해보자!
