알다가도 모를 API, 제대로 잡고 가기

12분

2025.01.10.

API?

API는 Application Programming Interface의 약자입니다. 인터페이스(Interface)라는 용어, API처럼 익숙하긴 한데 정확히 뭔지는 잘 모르겠죠? 영단어 Interface는 ‘접점’이라는 뜻을 갖고 있어요. 즉, 무언가가 또 다른 무언가와 소통하는 지점이라고 생각하면 됩니다.

UI와 리모컨

예를 들어 UI, User Interface라는 단어를 들어 보셨나요? 앱이나 웹사이트를 쓸 때, 우리가 보는 화면 구성을 UI라고 합니다. 이런 다양한 요소와 버튼들로 유저는 서비스와 상호 작용을 하잖아요. 그래서 인터페이스라고 하는 겁니다.

에어컨을 조작하는 리모컨도 인터페이스라고 할 수 있어요. 리모컨이 유저와 에어컨을 연결해 주는 접점에 있으니까요. 말이 되죠?

소프트웨어들의 접점, API

API도 이런 인터페이스의 한 종류입니다. 두 가지 소프트웨어, 즉, 두 가지 프로그램이 서로 소통할 수 있게 해 주는 역할이에요.

예를 들어 웹사이트에서 회원가입 버튼을 클릭하면, 이 사이트의 데이터베이스에 새로운 유저를 추가해 줘야 해요. 그러려면 클라이언트 쪽 프로그램이 API를 통해 서버 프로그램에 회원가입 정보를 보내줘야 합니다. 서버 프로그램은 그 정보들을 데이터베이스에 추가해 주는 거죠.

어떤가요? 두 프로그램이 API를 통해서 소통했죠? 클라이언트가 서버에게 요청을 보내고 서버가 클라이언트에게 응답하는 개념, 그 자체가 API를 활용하는 것입니다.

API를 쓰면 뭐가 좋을까?

API를 다룰 때 꼭 알아야 하는 중요한 개념 몇 가지가 있습니다.

리모컨에서 버튼을 누를 때, 우리는 에어컨이 어떤 동작을 할지는 알지만, 내부에서 어떤 메커니즘으로 돌아가는지는 모릅니다. API를 쓸 때도 마찬가지예요. 복잡한 사항들은 가려 놓아도 API 설명서를 잘 따르기만 하면 간편하게 소통할 수 있는 거죠.

이렇게 내부 사항들을 가려 놓았다는 특징은 또 다른 중요 포인트랑 관련이 있습니다. 바로 보안에 도움이 된다는 겁니다. 서버나 데이터베이스에는 노출이 금지된 정보들이 있을 수 있어요. API는 정해진 방식으로만 소통을 허락하기 때문에 외부와 소통하면서도 그런 정보를 잘 숨길 수 있는 거죠.

마지막으로, API를 쓰면 개발 생산성을 높일 수 있습니다. ‘네이버 API 쓰면 된다’, ‘Chat GPT API 써서 만들었다ʼ 이런 말 들어본 적 없나요? 꼭 우리가 직접 만든 API만 쓸 수 있는 게 아닙니다. 다른 기업에서 만든 프로그램을 가져다 쓸 수 있도록 다른 개발자나 회사에서 API를 제공해 주기도 합니다.

사실 API는 굉장히 다양한 형태로 존재합니다. 꼭 웹 개발이 아닌 다른 프로그램들을 만들 때도 API는 흔히 등장하는 용어예요. 다만 우리는 웹 개발의 기초로 API를 다루고 있으니까요. 클라이언트가 서버에게 HTTP 요청을 보내고, 서버가 적절한 HTTP 응답을 보내는, 웹 API에 대해 더 자세하게 배우도록 하겠습니다.

JSON

클라이언트가 서버에게 웹 API로 요청을 보낼 때는 데이터를 같이 보내야 하는 경우가 많습니다.

예를 들어서 회원가입을 한다고 할게요. 무작정 가입시켜 달라는 요청만 보내는 게 아니라, 가입하고 싶어 하는 새로운 유저의 계정 정보를 서버에 알려줘야겠죠. 마찬가지로 어떤 유저가 포스트에 좋아요를 눌렀다면, 누가 좋아요를 눌렀는지, 또 어떤 포스트에 좋아요를 눌렀는지 서버한테 알려줘야 합니다.

반대로 서버가 클라이언트에게 응답할 때도 데이터를 함께 보내 줘야 하는 경우들이 있고요.

이렇게 클라이언트와 서버가 소통할 때 데이터를 포함시키는 가장 대표적인 방식이 있습니다. 바로 ‘JSON’이라는 형식으로 데이터를 주고받는 거예요.

위의 이미지는 어떤 유저에 대한 정보를 담은 JSON입니다. 이름(name), 나이(age), 이메일(email), 학생인지 아닌지 여부(isStudent), 취미(hobbies), 주소(address), 이런 내용들이 담겨 있어요.

key와 value

JSON 데이터의 콜론 왼쪽에 있는 name, age, email, 이런 요소를 key라고 합니다. 콜론 오른쪽에 있는 요소는 value, 한국어로는 값이라고 해요. key와 value가 쌍으로 이루어져 있는 거죠.

일반적으로 key에는 따옴표를 붙여 줍니다. 반면 value는 데이터의 종류에 따라 달라요. 문자열, 그러니까 텍스트 형태의 데이터도 있고, 숫자 데이터도 있고, 또 대괄호를 쓴 목록도 있습니다.

중괄호를 쓴 것도 있는데, 이는 ‘객체’라고 부릅니다. 이를테면 주소(address) 데이터에는 몇 가지 세부 정보가 있습니다. 거리명(street)과 도시 이름(city), 우편번호(postal_code) 같은 요소들이 모두 주소의 세부 정보인 거죠. 이렇게 객체를 쓰고, 이 객체에 다시 key, value 쌍으로 속성을 넣어 주면 한층 체계적으로 데이터를 정리해 보내줄 수 있습니다.

JSON은 왜 표준이 되었을까?

어떤가요? JSON은 쉽게 해석할 수 있습니다. 보기만 해도 JSON이 어떤 정보들을 담고 있는지, 이 정보들 사이 어떤 위계가 있는지 쉽게 파악할 수 있죠? 사람도 사람이지만, 컴퓨터 입장에서도 해석이 간편합니다.

JSON은 JavaScript Object Notation의 약자입니다. 해석하자면, 자바스크립트가 객체를 표기하는 방식인 거죠. 실제로 자바스크립트로 프로그래밍을 할 때, 객체라는 자료형은 이 문법을 거의 그대로 따릅니다.

자연스럽게 JSON은 자바스크립트로 해석하기 굉장히 쉽습니다. 이는 자바스크립트에서 API 요청으로 JSON을 포함해 보낼 때, 코드 수준에서 별다른 처리가 필요 없다는 뜻입니다. 반대도 마찬가지입니다. API 요청에 대한 응답으로 JSON 형태의 데이터를 돌려받으면, 자바스크립트는 별다른 처리 없이도 데이터를 쓸 수 있어요. 자바스크립트는 웹 개발에서 가장 많이 쓰이는 언어이기 때문에, 이렇게 JSON이 데이터 통신의 표준이 된 거죠.

물론 서버 프로그램이 자바스크립트가 아니라 자바, 파이썬 등 다른 언어인 경우에는 JSON을 해당 언어로 해석하도록 처리를 해야 합니다. 그러나 JSON이 사실상 표준인 만큼, 어떤 언어를 쓰더라도 JSON을 처리하는 도구는 잘 만들어져 있습니다.

포스트맨으로 API에 요청 보내기

자, 그럼 이제부터 직접 API 요청을 보내보려고 합니다. JSON이 여기에서 어떻게 쓰이는지 같이 한번 살펴볼게요.

우선 우리가 이번 실습에 쓸 서비스를 보겠습니다. MBTI에 따라 어떤 색을 좋아하는지 볼 수 있는 간단한 ‘취향 설문 조사’ 사이트입니다. 여기서는 사람들이 미리 등록해 둔 취향을 볼 수도 있고, 내 취향을 새로 등록할 수도 있습니다.

API를 쓰려면 ‘API 문서’를 읽어야 합니다. API는 우리가 서버랑 소통할 수 있도록 해 주는 건데요. 이 문서는 서버에 어떤 식으로 요청을 보내야 하는지 적어둔 설명서라고 보면 됩니다. API 문서 역시 실습을 위해 준비했습니다. 다 읽지는 않고, 필요한 부분만 살펴봐도 괜찮습니다.

포스트맨(Postman) 시작하기

이 서비스에 API 요청을 보내기 위해 ‘포스트맨(Postman)’이라는 서비스를 사용할 거예요. 비개발자도 쉽게 쓸 수 있도록 되어 있습니다.

가장 먼저 회원가입을 해야 합니다. 회원가입하고, 이름을 입력하면 나만의 워크스페이스에 들어오게 됩니다. 그 공간에서 ‘+’ 버튼을 누르면 새로운 요청을 만들 수 있습니다.

데이터 요청하고 응답받기: GET

API 요청을 보내려면 두 가지 기본 요소가 있어야 합니다. 어떤 요청을 보낼지, 즉, 요청의 종류와 어디에 요청을 보낼지, 즉, 요청을 보내고자 하는 서버의 URL이죠. 우리는 유저들이 등록한 답변들 가운데 “14번째 답변을 받아오고 싶다”고 가정해 볼게요.

일단 API 문서로 가 보겠습니다. 상단에는 서버 호스트(learn.codeit.kr)가 나와 있습니다.

요청을 보낼 때도 이 호스트 주소를 쓰고 세부 경로들을 이어 써 주면 됩니다. 우리가 원하는 14번째 답변을 하나만 딱 받아오려면 어떤 식으로 요청을 보내야 할까요?

문서 하단으로 이동하다 보면 ‘설문 응답 조회’라는 섹션이 있습니다.

GET이라고 되어 있죠? ‘어떤 요청을 보낼지’에 해당하는 내용이에요. GET 말고 다른 선택지도 있지만, 보통 GET은 데이터를 받아오겠다는 의미예요. 참고로 POST는 데이터베이스에 새로운 데이터를 등록할 때, DELETE는 데이터베이스에서 데이터를 삭제할 때 씁니다. 우리는 데이터를 받아와야 하니 GET을 씁니다.

URL 경로는 어떨까요? id 부분에 실제 아이디 값을 넣어 주면 된다고 합니다. 서버 호스트와 API 문서의 설명을 참고해 URL을 구성한 다음, 우리에게 필요한 id 값 14를 넣어 주면 원하는 답변을 받아올 수 있는 거예요.

https://learn.codeit.kr/api/color-surveys/14

이제 포스트맨에서 GET을 선택하고, 위의 URL을 넣은 다음 Send를 클릭하면, API 요청이 보내집니다.

이어 API 요청에 대한 응답이 하단에 뜹니다. 포스트맨이 클라이언트로서 서버에 요청을 보냈기 때문에, 서버에서 이렇게 응답을 해 준 거죠. 응답을 한번 살펴볼까요?

익숙한 형태죠? 앞서 본 JSON 형태입니다. 웹 API 요청을 보내고 또 응답을 받을 때, 데이터를 같이 전달하고 싶으면 이렇게 JSON 형태로 전달합니다. JSON은 굉장히 단순해 어떤 정보들이 있는지 직관적으로 파악할 수 있죠.

일단 JSON에는 답변이 생성된 날짜(createdAt)랑 수정된 날짜(updatedAt)가 나옵니다. 지금은 숫자 형태지만, 이를 공식에 따라 변환시키면 우리가 이해할 수 있는 날짜가 나옵니다. 답변한 유저의 아이디(id)도 나오고, MBTI가 나오며, 또 이 사람이 어떤 색을 골랐는지 색깔 코드(colorCode)가 나옵니다.

자, 이렇게 우리의 첫 API 요청을 보내 봤습니다. 생각보다 어렵지 않죠? 이제 API 요청과 응답을 더 자세하게 들여다보며 조금 더 복잡한 요청도 한번 보내 볼게요.

복잡한 요청 보내기: POST

첫 번째 요청으로 설문 답변을 받아왔으니, 이번에는 새로운 설문 답변을 추가하라는 요청을 해 보겠습니다. API 문서의 ‘설문 응답 생성’ 섹션을 참고하겠습니다.

이번에는 GET 요청이 아니라 POST 요청입니다. 보통 데이터베이스에 새로운 데이터를 추가할 때는 이렇게 POST 요청을 씁니다.

다만, 이번에는 단순히 요청 종류랑 경로 URL만이 아니라 정보를 같이 보내야 합니다. 당연히 내용이 있어야 설문 답변을 생성할 수 있겠죠. 어떤 내용을 써야 할지는 문서에 나와 있습니다. MBTI, 좋아하는 색의 색깔 코드(colorCode), 비밀번호(password)를 필수로 보내야 한다고 하네요. 정리하면 아래 이미지처럼 종류와 경로, 정보를 모아 보내야 한다는 뜻입니다.

포스트맨에서 써 볼게요. URL을 복사해 붙여 넣고, 요청 종류는 POST로 바꿉니다. 이 상태 그대로 요청을 보내면 어떨까요?

응답이 오긴 오지만, Invalid MBTI, 즉, ‘유효하지 않은 MBTI가 왔다’는 메시지가 뜹니다. 우리가 정보를 아예 보내지 않았으니 문제가 생긴 거죠. 이 에러 메시지를 자세히 보면 ‘400 Bad Request’라는 문구가 뜨는데요. 이 400이라는 숫자를 상태 코드라고 합니다. API 요청에 문제가 있으면 응답이 올 때, 이렇게 400이라는 상태 코드가 같이 오는 거예요.

어떻게 수정해야 할까요? 경로 입력창 아래 Body라는 탭을 클릭해 보세요. ‘none’이라고 나온다면 우리가 요청에 데이터를 포함시키지 않았다는 의미에요. 대신 ‘raw’를 클릭해 보겠습니다. 다른 선택지도 있긴 한데 우리는 표준인 JSON으로 하겠습니다. 이는 요청에 JSON 데이터를 포함시키겠다는 의미입니다.

이제 추가하고 싶은 대로 예시의 JSON 정보를 수정하겠습니다. MBTI는 ISFP, 색은 hexcode 가운데 하나로 정하고 코드를 붙여 넣겠습니다. 다시 요청을 보내면, 이번에는 상태 코드가 ‘201 Created’, 즉, ‘생성에 성공했다’는 메시지가 올 겁니다. 응답 데이터 역시 JSON으로 돌아왔습니다.

API 요청에는 무엇이 필요할까?: HTTP 메소드와 URL

이제 API 요청이랑 응답을 조금 더 디테일하게 살펴볼게요.

API 요청할 때, GET, POST, PUT, PATCH, DELETE 등을 선택할 수 있었습니다. 우리가 ‘어떤 류의 요청을 하는지’ 나타내는 건데요. 이를 HTTP 메소드라고 합니다.

앞서 나열한 것들이 가장 대표적입니다. GET은 데이터를 받아오는 것, POST는 새로운 데이터를 추가하는 것, PATCH는 이미 존재하는 데이터를 부분적으로 수정하는 것, PUT은 존재하는 데이터를 통째로 수정하는 것, 그리고 DELETE는 데이터를 삭제하는 것을 의미합니다. 물론 다른 메소드도 있지만, 일단은 제일 많이 쓰이는 이 다섯 개 정도만 알아도 됩니다.

다음으로 요청을 보내려면 URL을 써야 합니다. API 문서를 보면 URL이 어떤 형식으로 되어 있는지 알 수 있는데요.

이때 URL은 전부 동사가 아니라 명사형입니다. 이게 어떤 의미일까요? 예를 들어 새로운 설문 응답을 생성한다고 했을 때, URL이 color-surveys처럼 명사형이 아닌 create-color-surveys 이런 동사형으로 하고 싶을 수도 있습니다. 그런데 그렇게 하기보다는 color-surveys라고 되어 있는 게 일반적이라는 뜻이죠.

그러니 URL 설계를 할 때, 우리가 어떤 액션을 취하고 싶은지는 HTTP 메소드로, 그 액션의 대상은 URL로 써 주는 겁니다. 예시에서는 color-surveys, 즉, 설문 응답이 액션의 대상이며, POST는 액션입니다. 이를 해석하자면 ‘설문 응답을 생성해 주겠다’는 거죠.

이러한 방식은 모두 권장 사항입니다. 이렇게 권장 사항을 잘 따라서 설계한 API를 RESTful한 API라고 합니다. 물론 권장인 만큼 따르지 않더라도 동작은 하지만, RESTful한 API를 설계하면 다양한 이점이 있습니다. 그래서 만약 나중에 API를 직접 만들어야 한다면, 어떻게 해야 RESTful한 API를 설계할 수 있을지 공부해야 합니다.

API 요청과 응답의 부가 정보들

API 요청에 들어가는 부가 정보들은 또 무엇이 있을까요?

우선 Headers에는 어떤 클라이언트가 요청을 보내는 건지에 대한 내용이 담겨 있습니다. 포스트맨으로 요청을 보냈다면, PostmanRuntime이라고 나옵니다. 보통 이 공간에는 보안 관련 정보나 API를 통해 어떤 형식의 데이터를 주고받을지 같은 다양한 내용들을 담기도 합니다.

Body에는 API 요청과 함께 보내고 싶은 데이터를 포함합니다. 보낼 데이터가 없으면 none을, 보낼 데이터가 있으면 어떤 데이터를 보내는지에 따라 선택할 수 있어요.

응답도 요청이랑 형태가 비슷한 부분이 꽤 있습니다. 부가 정보가 들어 있는 Header 부분이 있고, 또 응답에서 보내 주고자 했던 데이터는 Body에 JSON 형태로 들어가 있습니다.

다만 응답에는 추가로 Status 코드, 상태 코드가 있어요. 요청이 어떻게 처리되었는지 나타내는 세 자릿수 숫자입니다. 보통 가장 앞에 2가 붙어 있으면 성공적이었다는 것, 앞에 4나 5가 붙어 있으면 뭔가 오류가 발생했다는 거예요.

마치며

지금까지 API의 기본 개념부터 시작해 간단한 예제를 살펴보았습니다.

API. 여전히 조금 모호하다고 느낄 수도 있지만, IT 업계에서 일하려면 필수로 알아야 할 개념입니다. ‘두 가지 소프트웨어, 즉, 프로그램이 소통할 수 있게 해 주는 접점’이라는 핵심을 잊지 않고 차근차근 익혀 보세요.

원본 강의 보러 가기

로그인하고 자유롭게 의견을 남겨주세요.