API 명세서 알아보기 A to Z

GongBaek·2024년 4월 30일

Database REST API server

🎉 API 명세서

최근 아는 기획자분께 API 명세서에 대해 질문을 받았습니다.
API 명세서란 무엇인지, 어떻게 사용하는 것인지 기획자도 알면 굉장히 긍정적인 부분이라 생각해 글을 적어볼까 합니다!!

`API 명세서란?`

API가 어떻게 이루어져 있는지 자세히 적어놓은 문서를 말합니다!!

`API란?`

저희가 서버에서 주로 이야기하는 API는 정확히는 REST API 를 말해요! 일반 API랑은 엄연히 다른 개념입니다 🤔

그럼 서버에서의 REST API 는 뭘까요? IBM에서는 이를 다음과 같이 정의하고 있습니다.

애플리케이션이나 디바이스가 서로 간에 연결하여 통신할 수 있는 방법을 정의하는 규칙 세트

굉장히 명쾌한 답변이죠? 이를 정리하면 API 명세서 란 다음과 같다고 볼 수 있답니다 👍

통신할 수 있는 방법을 자세히 적어놓은 문서

여기서 서버 개발자가 하는 역할은 DB를 구성하고 저장소에 가진 데이터를 효율적으로 전달하는 것입니다!
그렇다면 하나 더 알아볼까요?

`DB란 뭘까요?`

데이터베이스(Database)의 약어입니다.
데이터베이스란 말 그대로 데이터의 기반을 뜻하는 말로, 저희가 집을 지을 때 기반을 뜻합니다.

결국 DB는 어디에 뼈대를 놓고 어떻게 생긴 기둥을 세울지 정하는 부분이라고 볼 수 있어요~~!!
언제나 기초공사는 잘 되어있어야겠쬬?! 이는 서버 개발자분들이 잘 해주실거라고 믿고 가시면 됩니다 🤣

어떤 위치에 어떤 정보를 저장하고, 어떤 방식으로 저장이 되는지 모두 DB에서 이루어집니다!
이러한 정보를 우리가 사용할 수 있도록 적어놓은 것이 API 명세서 라고 볼 수 있습니다!!

본격적으로 API 명세서를 읽어볼까요?

지금까지 읽기에 앞서 작은 배경지식을 쌓아 보았습니다.
대표적인 오픈소스로 알려져 있는 Reqres를 예시로 들어볼까 합니다!

위 사이트를 들어오셔서 스크롤을 내려보시면 다음과 같은 화면이 나옵니다.
다음은 Reqres에서 제공하는 API 명세서라고 볼 수 있습니다.

사실 그렇게 친절한 명세서는 아닌데요, 변수의 자료형이나 사용법 등등 모두 적어서 전달하는 API 명세서도 많거든요!! 하지만 굉장히 Basic한 예시를 들고왔으니 일단 쭉 읽어가면서 알아보죠!

이 부분은 서버와 통신하면서 진행하는 업무를 나타냅니다!

GET, POST, PUT, PATCH, DELETE가 있으며
각각의 역할을 간략하게 소개하자면 다음과 같습니다.

GET: 데이터를 받아옵니다. (ex: 회원정보 보기)
POST: 데이터를 전송합니다. (ex: 회원가입)
PUT: 입력한 데이터를 새로 추가합니다. 기존에 이미 데이터가 있다면 덮어씌웁니다. (ex: 게시글 등록 및 수정)
PATCH: 기존에 입력한 데이터를 수정합니다. (ex: 닉네임 변경)
DELETE: 데이터를 삭제합니다. (ex: 회원탈퇴)

이 부분은 각각 API의 이름을 대략적으로 적어놓은 부분입니다.

가볍게 읽고 이런 역할을 하는 친구구나~ 하고 넘어가주시면 됩니다.

Request와 Response를 알아볼까요?

Request 는 서버에 저희가 보내는 요청,
Response 는 서버에서 저희에게 보내는 요청을 말합니다.

항상 Request가 선행되어야 이루어지는 작업이며,
Request가 없으면 서버 통신은 이루어지지 않습니다.

형태는 유사해서 묶어서 알아보도록 합시다!!

이 부분은 우리가 전송해야 하는 부분입니다. 위는 GET일 때의 Request고,

이는 POST일 때의 Request입니다.

어떤 차이인지 보이시나요?

경로가 조금씩 다르고 보내는 형태가 조금씩 다르죠?!
이렇게 {} 에 묶인 형태를 저희는 BODY 라고 부르고, /api/users 는 PATH 라고 부릅니다.

이러한 BODY 나 나중에 나올 HEADER, QUERY 등의 친구는 필수적인 요소는 아닙니다!!
이는 서버가 어떻게 이루어지고, 어떤 역할을 하는지에 따라 달라질 수 있습니다.

BODY는 말 그대로 보내는 몸체, 즉 덩어리를 뜻합니다.
PATH는 길, 즉 어떤 경로로 이동해야 하는지를 뜻합니다.

그런데 위의 PATH에서 ?page=2 라는 이상한 친구를 볼 수 있죠?
이친구는 QUERY 라고 부르는 친구로, user의 목록 중에서도 특히 2페이지에 있는 친구를 보고 싶을때 사용합니다.

그렇다면 PATH와 QUERY는 어떻게 차이가 있나요?

PATH 는 주로 그 경로에 있는 데이터 그 자체를 식별하고 싶을 때 사용합니다.
QUERY 는 주로 정렬된 데이터를 구별해서 가져오고 싶을 때 사용합니다.

LIST USERS라는 API를 눌러보면 /api/users?page=2 라는 페이지로 정렬된 유저 리스트 정보를 가져오고 있고,
SINGLE USER를 눌러보면 /api/users/2 라는 2번 유저에 대한 정보를 가져오고 있습니다.

슬슬 감이 오시지 않나요? 다음 내용으로 넘어가보죠~~

BODY를 알아볼까요?

{
    "data": {
        "id": 2,
        "email": "janet.weaver@reqres.in",
        "first_name": "Janet",
        "last_name": "Weaver",
        "avatar": "https://reqres.in/img/faces/2-image.jpg"
    },
    "support": {
        "url": "https://reqres.in/#support-heading",
        "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
    }
}

저희가 사용하는 BODY의 형태는 주로 JSON이라 부르는 형태로,
클라이언트는 이러한 JSON을 받아 후가공을 거쳐 사용합니다.

이러한 BODY 안에는 서버가 가지고 있는 데이터베이스에서 어떤 부분을 담당하는지 나타나 있습니다.
각각의 자료형 역시 클라이언트의 재량이 될 수 있으며, 이를 어떻게 사용할지는 API 명세서를 통해 명확히 전달되어야 혼란을 방지할 수 있습니다.

예를 들어 id는 각 회원의 고유번호를 말합니다. 번호이므로 정수형을 뜻하는 Int라는 자료형을 사용하고 있으며, avatar는 각 회원의 프로필 사진 링크를 담당합니다. 따라서 문자열을 뜻하는 String이라는 자료형을 담당한다는 것을 볼 수 있죠.

이는 서버 개발자가 좀 더 직관적으로 정리해줄 수 있고,
때로는 이렇게 간략하게 적혀있을 수도 있습니다!!

하지만 id나 avatar라는 이름은 데이터베이스에서 중요한 Column(열) 이라는 부분을 담당하고 있으므로 오타가 생기면 서버 통신을 할 수 없습니다 💩

사실 헤더까지 아신다면 API 명세서를 읽으실 때, 거의 문제가 없으실거예요!
이는 서버와 통신을 주고받을 때 포함된 보조 데이터 를 말합니다.
여기에는 가볍지만 꼭 보내줘야 하는 데이터가 포함되는데요,
앞서 나온 유저의 고유번호를 이로 전달할 수 있습니다!!

하지만 단순하게 이러한 고유번호를 주고받는다면, 보안 등에서의 안정성 문제가 있겠죠?! 이를 위해서 나온게 Token 이라고 할 수 있습니다. 로그인 할 때 서버로부터 인증 토큰을 받고, 우리는 고정된 정보가 아닌 이렇게 인증된 입장권을 가지고 사용할 수 있습니다!!

마치 놀이공원에 들어갈 때 주민등록증을 계속 들고다니면서 타는 것이 아니라,
입장권을 따로 사용하는 것처럼 말이죠!
이와 관련해서는 구글에 토큰 인증 방식을 따로 검색하시면 더 자세한 정보를 아실 수 있습니다 🤗

헤더에 대한 API 명세서 예시는 따로 드린다면 다음과 같습니다.