Intro
포스팅을 시작하기에 앞서서
이번 포스팅의 주제는 "API에 대하여" 이다. 웹 개발을 시작한지 얼마 안 됐던 병아리 시절부터 API는 정말 자주 들었던 단어인데 사실 처음 접했을 때 나에게는 좀 모호하고 이해하기 힘든 개념이었다. 많은 초보 개발자들이 그 때의 나처럼 API에 대해 어려워하고 무서워할 것 같아서 이에 대한 쉽고 간단한 가이드라인을 만들어 소개하고자 한다.
아직 기술적으로 높은 수준의 이해를 한 것은 아니어서 내용이 100% 정확하지 않을 수는 있지만 그래도 초보자 입장에서 어떤 느낌인지 대충 감을 잡을 수 있게 열심히 정리해보도록 하겠다!
API에 대한 소개
간단한 정의
API는 무엇의 약자일까? API는 "어플리케이션 프로그래밍 인터페이스(Application Programming Interface)"를 줄인 말이다. 개발 관련 용어는 대부분 처음 접하는 입장에서 단어만 봐서는 본래의 뜻을 알 수 없는 경우가 많은데 이 경우 역시 그런 케이스이다.
그래서 간단하게 설명하자면 API는 어떠한 서비스를 사용할 때의 사용 설명서이다. 덧붙이자면 API를 사용할 때 어떤 URL로 요청을 보내야 하는지, 요청을 보낸다면 응답은 어떤 식으로 오는지 등의 정보를 상세하게 적어놓은 설명서라고 할 수 있다.
사용 설명서라는 것은 해당 서비스를 사용하기 위한 "표준적인 방법"이며 이 표준이란 것이 영어로 인터페이스이다. 바로 여기서 API, 즉 어플리케이션 프로그래밍 인터페이스가 나온 것이다.
예시
사용 설명서라는 개념의 이해를 돕기 위해 한 가지 예시를 들고자 한다. 우리가 아는 유명한 API 중에는 구글 지도 API, 파파고 번역 API와 같은 것들이 있는데 그 중 파파고 번역 API를 사용한다고 가정해보자.
만약 파파고 번역 API를 사용하고 싶다면, 먼저 HTTP 요청을 보낼 URL이 필요할 것이다. 다음으로는 어떤 HTTP Method(GET, POST...)를 사용할지 알아야 할 것이고 요청 Body에 번역하고자 하는 텍스트, 원본 언어와 목적 언어 등의 정보 역시 첨부해야 할 것이다.
API 요청을 위해서는 위와 같이 다양한 요소들이 필요한데 이것들에 대한 설명이 각 API 문서에 기재되어 있다(친절한 API의 경우 예제 코드를 제공해줄 때도 많다). 이런 면에서 볼 때 API를 해당 서비스를 사용할 때의 사용 설명서라고 할 수 있는 것이다.
하지만...
하지만 일반적으로 개발자들은 API에 대해서 이야기할 때 그냥 "무슨 API 끌어와서 쓰자" 라는 식으로 많이 얘기하며, 아무래도 본래 뜻처럼 어떤 서비스의 사용 설명서라는 개념보다는 그냥 서비스 그 자체로 인식하는 경우가 많다. 따라서 이해를 돕기 위해 해당 포스팅에서는 API를 그냥 쉽게 서비스 그 자체로 생각하라고 권하고 싶다.
예를 들어 "파파고 번역 API를 사용한다"라고 할 때 "파파고 번역 사용 설명서를 사용한다"라고 생각하지 말고 그냥 "파파고 번역 서비스를 사용한다"라고 생각하자는 것이다. 엄밀히 말하자면 정확한 개념은 아니지만 처음 접하는 사람의 입장에서는 이 쪽이 더 이해하기 편할 것이다.
API의 종류
외부 API와 내부 API
이해를 쉽게 하기 위해 앞에서 설명한 API의 예시는 대부분 외부 API의 예시를 들었다. 구글 지도 API와 파파고 번역 API 등은 모두 외부 API에 속하며 반대로 내부 API 또한 존재한다. 둘의 차이점에 대해 알아보자.
간단하게 외부 API는 우리가 생각하는 그 "외부"로부터 오는 API가 맞다. 보통 현재 내가 속한 개발 조직이나 팀원이 아닌, 기업이나 기타 서비스 제공자가 제공하는 API를 외부 API라고 한다.
내부 API는 그 반대이다. 내가 속한 조직 내에서 내가 개발하는 어플리케이션을 위해 제공하는 API라고 할 수 있다. 한 가지 예를 들어보자.
예를 들어 웹 프론트엔드 개발자로서 회원가입 UI를 만들었을 때 이것을 실제 회원가입 기능을 하는 API와 연결하고 싶을 것이다.
이 API는 대부분 조직 내의 백엔드 개발자가 개발하게 되는데 이러한 것들이 모두 내부 API에 속한다.
둘의 간단한 차이점은 외부 API는 남이 만든 API를 가져다 쓰는 것이고 내부 API는 우리 팀원이 만든, 또는 내가 직접 만든 API를 가져다 사용한다는 것이다!
그러면 API는 어떻게 사용할까?
먼저 API URL과 HTTP Method를 찾자
모든 API는 요청할 때 URL 정보와 HTTP Method를 필요로 한다. URL이 무엇인지는 누구나 알 것이며 HTTP Method는 GET, POST와 같은 HTTP 요청 방식을 뜻한다. 제일 먼저 이 두 정보를 찾아보자.
예를 들면 "/join" URL에 POST 방식으로 API 요청을 보낼 수 있다.
필요한 요청 Header 및 Body 정보를 확인하자
흔히 사용하는 GET 방식과 POST 방식 중 GET 방식의 경우, URL과 HTTP Method만으로 요청이 가능하다. 하지만 POST 방식의 경우, 대부분 HTTP Body에 담긴 추가 정보를 필요로 한다.
이 경우에는 여러가지 케이스가 있는데 첫 번째는 로그인과 같이 API 동작을 위해 정보가 필요한 경우이다. 만약 로그인을 하려 한다면 당연하게도 로그인 아이디나 비밀번호 정보 등이 빠질 수 없을 것이다. 따라서 API 요청 시 해당 Form 정보를 HTTP Body에 담아 보내는 것이다(최근엔 대부분의 요청과 응답 데이터가 JSON 타입으로 이루어진다).
두 번째는 외부 API를 사용할 때 흔히 생기는 경우인데 API 호출을 위한 API Key가 필요한 경우이다. 외부 API의 경우 해당 기업의 자원을 할당하여 서비스를 제공하는 것이기 때문에 개인이 API를 무한정 사용하지 못하게 하는 것이 보통이다. 주로 이용 횟수에 따라 요금을 부과하는 방식으로 운영되는데 이 때 누가 API를 사용하는 것인지 식별하기 위해 사용자마다 API Key를 부여하며 API 요청 시에는 이 Key를 HTTP Header에 첨부해야 요청이 가능하다.
이 외에도 사용하고자 하는 서비스의 해당 API 문서를 참고한다면 요청에 어떠한 정보가 필요한지 알 수 있다. 잘 읽어보고 알려주는대로 한다면 문제 없을 것이다!
HTTP 요청을 보내는 방법
이제 요청에 필요한 정보를 모두 알았으니, 이를 코드로 풀어내기만 하면 된다. HTTP 요청을 위해 사용하는 기술이나 라이브러리 등은 언어마다 모두 다른데, 해당 포스팅에서는 내가 주로 사용했던 자바스크립트와 자바에 대해 중점적으로 다뤄볼 것이다.
자바스크립트
먼저 자바스크립트에서의 HTTP 요청은 Ajax 통신을 통해 이루어진다. 자세한 개념은 생략하며, 비동기적으로 서버와 데이터를 주고받는 기술이라고 알아두면 된다. 최근 Ajax 통신을 처리할 수 있는 가장 인기있는 라이브러리는 Axios인데, 간결하고 직관적인 문법과 더불어 JSON 데이터를 자바스크립트 객체로 자동으로 파싱(변환)해주기 때문에 아주 편리하다. 우리는 이 Axios 라이브러리를 사용해 API 요청을 진행할 것이다.
Axios
Axios의 사용 예시는 다음과 같다. 어떤 회원의 로그인 정보를 저장한 data라는 자바스크립트 객체가 있을 때, "/api/login"이라는 URL에 POST 방식으로 로그인을 요청한 모습이다.
let data = {
loginId = "user1",
loginPw = "0000"
};
axios.post('/api/login', data)
.then((res) => {
// 요청 성공 시의 코드
// 서버로부터의 응답을 출력한다.
console.log("res -> " + res):
})
.catch((err) => {
// 요청 실패 시 코드
// 실패 시의 에러 응답을 출력한다.
console.log("err -> " + err):
});자바
자바에서, 그 중에서도 Spring 프레임워크에서 API 요청을 보내는 방법에는 RestTemplate과 WebClient 등이 있다.
RestTemplate
RestTemplate의 사용 예시는 다음과 같다. RestTemplate 객체를 선언한 후, 지정된 URL에 requestEntity를 담아 POST 요청을 보낸다. requestEntity에는 요청 Body 정보로 사용자 loginId와 loginPw 값을 설정하였다.
RestTemplate restTemplate = new RestTemplate();
String url = "/api/login";
// 요청 바디 객체 생성
RequestObject requestObject = new RequestObject();
requestObject.setLoginId("user1");
requestObject.setLoginPw("0000");
// 요청 엔티티 요청 바디 설정(헤더 역시 설정 가능)
HttpEntity<String> requestEntity = new HttpEntity<>(requestObject);
// HTTP 메서드를 설정하여 요청 보내기
ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
// 응답 코드 확인
int statusCode = response.getStatusCodeValue();
System.out.println("응답 코드: " + statusCode);
// 응답 내용 출력
String responseBody = response.getBody();
System.out.println("응답 내용: " + responseBody);WebClient
Spring 5 이후로는 비동기적으로 요청과 응답을 처리할 수 있는 WebClient가 등장하였다. 아무래도 기존의 RestTemplate보다 더 최신기술이고, 여러가지 기능상의 장점이 있으므로 이 쪽을 쓰는 것을 추천한다.
WebClient의 사용 예시는 다음과 같다. 마찬가지로 지정된 URL에 사용자 아이디, 비밀번호 정보를 Body에 담아 POST 요청을 보냈다. 특이사항으로는 Axios와 마찬가지로 비동기적 요청이 가능하며, 요청이 완료되었을 때의 로직과 실패했을 때의 로직을 분리하여 처리할 수 있다.
WebClient webClient = WebClient.create();
String url = "/api/login";
// 요청 바디 객체 생성
RequestObject requestObject = new RequestObject();
requestObject.setLoginId("user1");
requestObject.setLoginPw("0000");
Mono<String> response = webClient.post()
.uri(url)
.bodyValue(requestObject)
.retrieve()
.bodyToMono(String.class);
.subscribe(
responseBody -> {
// 성공적인 처리
System.out.println("응답 내용: " + responseBody),
},
error -> {
// 에러 처리
System.err.println("에러 발생: " + error.getMessage());
}
);마무리
정리
이렇게 API에 대한 개념적 설명부터 시작해서 API의 종류, 요청에 필요한 요소들 및 사용 방법까지 알아보았으며 해당 과정이 어느정도 이해가 되었다면 API를 사용할 준비가 완료된 것이다.
다만 쉬운 이해를 위해서 API 개념과 HTTP 요청에 관한 자세한 내용은 다소 생략했기에 시간이 될 때 해당 분야에 대해 깊이 공부해볼 것을 추천한다. 특히 HTTP 프로토콜에 관해서 찾아보는 것이 큰 도움이 될 것이다!
여담
사실 나는 처음 API를 사용하고 싶었을 때 이것을 어떻게 사용해야 하는지, 심지어 어떤 키워드로 검색해야 하는지조차 몰라서 굉장히 헤맸던 경험이 있다.
대략 1년 전, 교내 팀 프로젝트에서 웹 프론트엔드 역할로서 간단한 쇼핑몰 페이지를 만들고 있었는데 상품 목록을 서버로부터 불러오는 기능을 구현해야 했다. 그런데 해당 데이터를 어떻게 불러와야 할지, 또 코드를 어떻게 짜야 할지에 대해서 전혀 감이 잡히지 않았다.
결과적으로는 끈질긴 구글링을 통해 이
"클라이언트와 서버가 무언가 기브 앤 테이크하는 행위"를"API를 요청한다"라고 부른다는 것을 알게 되고, 사용 방법도 어렴풋이 알게되었다. 하지만 그 과정이 많이 힘들었고, 시간에 쫒겨가면서 마감해야 했던 프로젝트라 심적인 부담도 컸었던 것 같다.
아마 그 때 경험에 비춰 "초보 개발자들에게 API 사용에 관한 일련의 가이드라인이 있으면 좋을 것 같다"라는 생각이 들지 않았나 싶다. 아무튼 결국 이렇게 관련된 포스트를 올리게 되었고 해당 내용이 많은 사람들에게 도움이 되었으면 하는 바람이다!
이것으로 포스팅을 마치도록 하며, 앞으로 다양한 API를 활용하여 더 멋진 웹 서비스를 만들어보도록 하자. 파이팅!
