api 명세서란 무엇인가…api 뜻과 api 키 발급까지 정리

api 명세서는 어떤 프로그램이 외부에서 자신의 기능을 쓸 수 있도록 열어 둔 통로, 즉 api가 어떤 방식으로 호출되고 어떤 값을 주고받는지를 문서로 정리해 둔 것을 말한다. 이 글은 api 뜻부터 api 키, api 키 발급, 그리고 apify처럼 검색에 함께 뜨는 낱말까지 한 번에 짚어, 이 주제를 찾아본 사람이 더 찾아볼 필요가 없도록 정리한다.

api란 무엇인가

api는 응용 프로그램 인터페이스의 줄임말로, 서로 다른 프로그램이 직접 코드를 들여다보지 않고도 정해진 규칙대로 요청과 응답을 주고받게 해 주는 약속이다. 예를 들어 지도 화면을 보여 주는 서비스는 지도 정보를 직접 만들지 않고, 지도를 관리하는 다른 서버에 정해진 형식으로 요청을 보내 결과를 받아 온다. 이때 어떤 주소로 요청을 보내야 하는지, 어떤 값을 넣어야 하는지, 어떤 형태로 답이 오는지를 몰라도 되는 것이 아니라 오히려 정확히 알아야 하는데, 그 약속을 적어 둔 문서가 바로 api 명세서다. 결국 api가 개념이라면 api 명세서는 그 개념을 실제로 쓸 수 있게 만든 설명서에 해당한다.

api 명세서는 무엇을 담나

api 명세서에는 보통 요청을 보낼 주소, 어떤 방식으로 요청하는지(값을 가져오는지, 새로 만드는지, 고치는지, 지우는지), 요청할 때 함께 보내야 하는 값의 이름과 형식, 그리고 응답으로 돌아오는 값의 구조가 담긴다. 여기에 더해 요청이 잘못되었을 때 어떤 신호를 돌려주는지, 즉 오류 상황을 어떻게 알려 주는지도 함께 적어 둔다. 이런 항목이 빠짐없이 정리되어 있어야 이 api를 처음 쓰는 사람도 직접 만든 사람에게 묻지 않고 코드를 짤 수 있다. 반대로 명세서가 허술하면 같은 팀 안에서도 서로 다른 값을 기대하며 코드를 짜게 되어 나중에 맞춰 보는 과정에서 시간이 크게 든다.

api 명세서를 쓰는 형식은 자유롭게 글로만 적을 수도 있고, 정해진 표기 규칙을 따라 기계도 읽을 수 있는 형태로 만들 수도 있다. 정해진 규칙을 따르면 문서를 바탕으로 테스트 화면을 자동으로 만들거나, 명세서와 실제 동작이 다른지 자동으로 확인하는 도구를 붙일 수 있다는 장점이 있다. 다만 어떤 형식을 쓰든 핵심은 같아서, 이 api를 처음 보는 사람이 명세서만 읽고도 어떤 값을 보내면 어떤 값이 돌아오는지 그려낼 수 있어야 제 역할을 하는 문서라고 볼 수 있다.

api 키와 api 키 발급, 헷갈리기 쉬운 낱말들

api 키는 이 api를 누가 쓰고 있는지 구분하기 위해 발급하는 일종의 식별값이다. 아무나 요청을 보낼 수 있게 열어 두면 누가 얼마나 쓰는지 알 수 없고 악의적인 사용을 막기도 어려우므로, 서비스를 제공하는 쪽에서 사용자마다 고유한 키를 내주고 요청할 때마다 그 키를 함께 보내도록 요구하는 방식이 흔히 쓰인다. api 키 발급은 그 서비스가 정해 둔 절차를 따라야 하며, 서비스마다 신청 방법과 발급 조건이 다르므로 이용하려는 서비스의 공식 안내를 직접 확인하는 것이 가장 정확하다.

검색어 중에는 apic처럼 api와 비슷하게 생긴 말이나, apixaban처럼 전혀 다른 분야에서 쓰이는 말도 함께 뜨는데, 이런 말은 api와는 관계없는 다른 분야의 고유한 용어일 뿐이니 api 명세서를 찾다가 함께 보이더라도 혼동할 필요는 없다. apify라는 이름 역시 자동화나 데이터 수집을 표방하는 해외 서비스 이름 가운데 하나로 알려져 있는데, 이 글에서는 특정 서비스를 추천하거나 순위를 매기지 않으며, 어떤 도구를 쓸지는 각자 필요한 기능과 정책을 직접 비교해 정하는 것이 맞다.

실무에서 자주 막히는 지점

api 명세서를 다루다 보면 가장 자주 부딪히는 문제는 문서와 실제 동작이 어긋나는 경우다. 처음 만들 때는 문서대로 동작하다가도 기능이 조금씩 고쳐지는 과정에서 문서 갱신을 놓치면, 문서를 믿고 코드를 짠 쪽에서 오류를 만나게 된다. 그래서 규모가 있는 조직에서는 코드가 바뀌면 문서도 함께 바뀌도록 도구로 묶어 두거나, 문서 자체를 코드에서 자동으로 뽑아내는 방식을 쓰기도 한다. 또 하나 자주 나오는 문제는 버전 관리로, 기존에 쓰던 api를 그대로 둔 채 새 기능을 추가한 api를 따로 만들어야 기존 사용자가 갑자기 작동을 멈추는 상황을 피할 수 있다.

상황에 따라 다르게 봐야 할 부분

api 명세서는 누가 쓰느냐에 따라 갖춰야 할 수준이 다르다. 같은 회사 안에서만 쓰는 api라면 팀이 이미 공유하는 배경지식을 전제로 간단히 적어도 되지만, 외부 개발자나 다른 회사에 공개하는 api라면 아무런 배경지식이 없는 사람도 읽고 바로 연결할 수 있도록 예시 요청과 예시 응답까지 자세히 적어야 한다. 값을 주고받을 때 개인정보나 민감한 정보가 포함되는 api라면 어떤 값을 반드시 암호화해서 보내야 하는지, 어떤 권한이 있어야 요청할 수 있는지도 명세서에 함께 밝혀야 나중에 다투는 일이 줄어든다. 반대로 내부에서 실험적으로만 쓰는 api라면 지나치게 형식을 갖추기보다 자주 바뀐다는 사실 자체를 문서 첫머리에 밝혀 두는 편이 오히려 실용적이다.

무엇부터 확인해야 하나

api 명세서를 처음 접하거나 만들어야 하는 입장이라면, 먼저 이 api가 내부용인지 외부 공개용인지부터 정해야 항목의 자세함 정도를 가늠할 수 있다. 그다음으로는 요청 주소와 방식, 주고받는 값의 형식, 오류 응답의 구조가 빠짐없이 담겼는지를 확인하고, api 키처럼 인증이 필요한 부분이 있다면 발급 절차와 사용 범위까지 명세서 안에 명확히 적혀 있는지 살펴야 한다. 마지막으로 문서가 실제 동작과 어긋나지 않는지는 한 번의 확인으로 끝나는 문제가 아니라 api가 바뀔 때마다 반복해서 맞춰 봐야 하는 일이라는 점을 기억해 두는 것이 좋다.

api 명세서를 둘러싼 궁금증은 결국 이 문서가 얼마나 정확하고 자세한지에 달려 있다. 특정 api를 실제로 쓰려면 명세서에 적힌 요청 주소와 값 형식, 인증 방식을 먼저 꼼꼼히 읽고, api 키 발급이 필요하다면 해당 서비스의 공식 안내 페이지에서 절차와 조건을 직접 확인한 뒤 진행하는 순서가 가장 안전하다.

· · · · · · · · · ·

스페셜타임스는 AI 기술의 도움을 받아 더 빠르고 다양한 뉴스를 독자에게 전달하기 위해 노력하고 있습니다.