※ 개인 학습을 위해 작성하는 내용으로 수정될 수 있습니다. (피드백 환영)
기획자가 API 문서를 꼭 봐야하는가?
안 봐도 됩니다. 기획-개발팀 내부에서 소통에 무리가 없다고 판단되는 경우 반드시 기획자가 API 문서를 볼 필요는 없습니다. 다만 기획자들은 업무 환경과 배경(전공 등)에 따라 개발 지식에 대한 이해도가 천차만별입니다. 때문에 습관적으로 모호한 표현(개발적 은어: 말아서 던진다든지, 가져와서 뿌려준다든지)을 사용하곤 하는데 이러한 습관을 고치기 위해 API 문서 보는 방법을 익혀야겠다고 생각했습니다. 따라서 기획자가 API 문서를 분석할 줄 알아야 하는 이유는 개발자에게 훈수두기 위함이 절대 아니며, 정확한 소통(해당되는 담당자에게 적절한 요청)을 하기 위함이라고 할 수 있습니다.
또한 API 문서를 이해할 수 있다는 건 스스로 어느 정도 진행 상황을 파악할 수 있다는 의미이기도 합니다. 예를 들어 상품 상세 페이지에서 어떤 항목을 추가하기를 원한다면 상품 정보 조회 및 등록 API에 대한 변경이 필요합니다. UI 변경 사항은 쉽게 파악할 수 있지만 서버 작업은 완료되었는지 눈으로 확인하기 어렵습니다. 이 때 API 문서를 보고 이해할 수 있으면 예상 영향도, 개발 진행도 등을 판단할 수 있습니다.
API는 무엇이고, 왜 필요한가?
API(Application Programming Interface 애플리케이션 프로그래밍 인터페이스[*], 응용 프로그램 프로그래밍 인터페이스)는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻한다. 주로 파일 제어, 창 제어, 화상 처리, 문자 제어 등을 위한 인터페이스를 제공한다.
출처: API 위키백과
API는 클라이언트와 서버 간 요청과 응답을 주고 받을 수 있게 만든 체계를 말한다. 이 체계에는 주소(자원), 데이터(표현), 처리 내용(행위)이 포함되는데, 클라이언트(User 단)의 요청에 해당하는 정확한 응답을 보내기 위해 서버 프로그램을 사전에 정의하는 것이다. 결과적으로 API 문서에는 어떤 데이터를 주고 받을지, 어떻게 처리하고 싶은지 정의한 내용이 담겨있다고 볼 수 있다.
이 요청-응답 체계의 각 요소를 살펴보면 주소는 서버 주소를 의미한다. 서버 주소는 서버 컴퓨터가 위치한 주소로, 호출하면 특정 기능을 수행하도록 한다. 예를 들어 카카오스토리 프로필 정보를 불러오기 위해 클라이언트는 카카오스토리 측에 '서버주소/프로필 가져오기'라고 신호를 보낸다. 카카오스토리 서버는 정보를 불러오는 기능을 수행하고 결과를 응답한다. 여기서 데이터는 프로필 정보를, 처리 내용은 '불러오기' 기능을 의미한다.
셀프 CHECK
- API의 구성 요소는?
- 데이터의 요청과 응답은 어떻게 이루어지나? (API의 구성 요소를 모두 포함하여 답할 것)
POST? GET? REST API?
데이터를 처리하는 요청은 크게 4가지로 구분할 수 있다.
- Create: 생성하다
- Read: 불러오다
- Update: 바꾸다
- Delete: 삭제하다
각 요청은 서버주소를 갖게 되는데, 게시판을 예를 들면 게시글을 생성하고, 불러오고, 바꾸고, 삭제하는 요청은 '서버주소/boardcreate', '서버주소/boardread', '서버주소/boardupdate', '서버주소/boarddelete' 의 주소를 가질 수 있다. 그런데 이렇게 데이터를 처리하는 CRUD 기능마다 이름을 붙이면 각 기능을 식별하기 어려워진다. 그래서 이를 규격화하기 위해 나오게 된 것이 REST(Representational-대표적인) API이다.
- Create: 생성하다->POST
- Read: 불러오다->GET
- Update: 바꾸다->PUT/PATCH
- Delete: 삭제하다->DELETE
실제 카카오스토리 프로필 가져오기 API 문서를 통해 용례를 살펴보면 다음과 같다.
카카오스토리 프로필 데이터를 불러오기(Read) 위해 /v1/api/story/profileread 와 같이 주소를 하나하나 생성, 지정하는 것이 아니라 GET 메소드를 사용하여 profile 주소를 호출하도록 하는 것이다.
404 에러? 500 에러?
이제 클라이언트가 요청한 내용에 대해 서버가 처리 결과를 응답해야 한다. 우선 성공인지, 실패인지를 응답해야 하고 실패했다면 이유가 무엇인지도 표현되어야 한다. 그렇다면 각 요청에 대한 서버의 응답 역시 규격화될 필요가 있다. 이러한 표현방식이 HTTP 상태 코드이다.
- 1xx (정보): 요청을 받았으며 프로세스를 계속한다
- 2xx (성공): 요청을 성공적으로 받았으며 인식했고 수용하였다
- 3xx (리다이렉션): 요청 완료를 위해 추가 작업 조치가 필요하다
- 4xx (클라이언트 오류): 요청의 문법이 잘못되었거나 요청을 처리할 수 없다
- 5xx (서버 오류): 서버가 명백히 유효한 요청에 대해 충족을 실패했다
이처럼 에러 유형을 구분할 수 있다면 문제의 원인을 짐작하는데 도움이 된다. 참고로 404 에러는 서버가 요청한 페이지(Resource)를 찾을 수 없음을 의미하고, 500 에러는 내부 서버에 오류가 발생하여 요청을 수행할 수 없음을 의미한다.
JSON 형식이란?
이러한 요청과 응답에는 데이터가 요구된다. 이 때 데이터를 주고받는 형식을 표준화한 것 중 하나가 JSON 형식이다.
JSON은 키와 값으로 구성되어 있으며 표기는 다음과 같다.
이를 종합하여 앞서 살펴본 카카오스토리 프로필 가져오기 API 문서의 Response를 살펴보면 다음과 같다.
한편 Request 시에도 데이터를 전달해야 하는 경우가 있는데 이를 요청 변수, 파라미터라고 한다. 가령 클라이언트는 카카오스토리 게시글 작성을 요청하기 위해 글과 이미지 파일을 전달해야 하며, 이 때 글과 이미지 파일이 파라미터이다.
서버에 저장? DB에 저장? 클라이언트에 저장?
앞서 API 문서를 보는 이유가 정확한 소통(해당되는 담당자에게 적절한 요청)을 하기 위함이라고 언급하였는데 이제 API 문서를 해석할 수 있게 되었으니 각 요소들이 어디에 저장되어 있는지, 어떤 담당자에게 요청해야 할지 파악할 수 있다. 가령 API를 통해 이미지의 URL을 서버에서 받아온다면 해당 이미지는 서버에 저장되어 있다고 짐작할 수 있다.
카카오스토리 프로필을 가져올 때 다음과 같이 이미지의 URL을 확인할 수 있고 서버에서 가져온다는 사실을 알 수 있다.
위에서 예시로 든 API 문서 내 모든 요소를 설명한 것은 아니며 부족한 내용이 있을 수 있다. 특히 REST API에 대한 내용은 좀 더 구체적으로 알아봐야 할 필요가 있다. 앞으로 차차 보완하도록 하며 다양한 API 문서에 익숙해지자!
댓글