프로젝트를 위한 API에 관한 고민 (엔드포인트 EndPoint)

원래 맡겼던 백엔드 분과 협의가 잘 되지 않았는지, 중간에 회사와의 연결이 끊어졌다.

모든 전말을 상세하게 아는 것은 아니지만, 가장 큰 부분은 회사에서 비즈니스를 생각하는 대표와 개발자의 생각이 서로 다른 채로 이야기가 진행되었던 것 같다.

즉, 커뮤니케이션 문제가 가장 크지 않았나 하는 생각이 든다.

그래서 글을 쓰고 있는 오늘을 기준으로 다음 주 화요일에 다른 외주 백엔드분을 만나서 미팅을 가지는데 함께 가기로 했다.

 

여기서 나의 고민은 크게 두 가지가 발생했다.

1. 기존 백엔드 분은 나와 아는 사이니 내가 일하기 편하게 도와줄 수 있었다. 그러나 외주에 맡긴다는 것은 나에게 필요한 것을 확실하게 내가 전달해야한다는 의미일 수도 있다.

2. 나와 함께 미팅을 가자는 말은 어느정도 내가 필요한 것들을 가서 보고 얘기를 하자고 하는 것일텐데... 그렇다면 나는 얼마만큼, 혹은 어떤 이야기를 할 수 있을까 즉, 아무것도 모른채 소위 호구만 잡히다가 오는 것은 아닌가 걱정이 되었다.

 

문제를 문제로만 안고 가기보다는 이를 어떻게 해결해야할지 고민했다.

주변 백엔드 분들에게 자문을 구했을 때 가장 많이 들은 말은 "프론트엔드 쪽에서는 API에 대해서 신경을 별로 안 쓰는 경우가 있더라. 외주를 받았을 때도 해주면 제대로 보지도 않고 일단은 좋다고 하는 경우가 있다. 사실 데이터가 전부라고 할 수 있는데 정확하게 안보고 나중에 물어보는 경우가 다반사더라." 였다.

그래서 이곳저곳 찾아보고, 자문을 구한 끝에 나온 스스로를 위한 솔루션은 "내 스스로가 API에 대해서 조금 더 알아야 하고, 미리 API 연결에 관한 그림을 그려서 가자" 였다.

그래서 API에 대해서 공부를 조금 해두려고 한다.

 

---

백엔드 분들과 이야기를 하는데 있어서, 계획을 하는데 있어서 나오는 말이 "API 명세" 라는 말이었다.

API 명세라는 것이 무엇일지 감은 오지만 정확하게 알아보려고 했다.

쉽게 말해서 기획서, UI 등이 나왔을 때 기능에 따른 명세를 작성 함으로써 필요한 기능들을 어떻게 요청하고 응답하여 사용할건지 정리해 놓은 가이드라고 볼 수 있을것이다.

 

그렇다면 명세를 정리하는 규칙이 있을까?

나의 경우 어떤 개발자 분은 스마트폰을 이용해서 간단하게 정리하여 문자나 카톡으로 보내는 경우부터, 엑셀 파일로 정리하는 정도까지도 보았다.

다시 말해 그 방법은 매우 다양하다.

정확하게 정해진 것은 없으며 그 팀이나 조직이 어떤 방식으로 하자고 설계원칙을 잘 정하기만 하면 된다.

 

여러가지 방법이 있지만 기본적으로 Method + EndPoint로 이루어진다.

예를 들자면 아래와 같은 방식이다.

Method	URI	Description
POST	/users/login	로그인
GET	/user/account/check-duplication/id/{id}	ID 중복체크
PUT	/posts/{post_id}/likes	좋아요 (like)
DELETE	/posts/{post_id}	게시글 삭제

이는 더 심플하게 쓰는 방법도 있지만 대체적으로 그 모습은 비슷하다.

 

---

API를 짜는데 있어서 반드시는 아니지만 중요한 것들이 있다.

여러가지 원칙이 있는데, 그 중 특히 중요한 것들을 꼽자면 아래와 같다.

1. 자원으로 *엔드포인트를 설정
2. 엔드포인트는 명사로 사용 할 것
3. 좀 더 넓은 자원이 앞으로 올 것

이 외에도

• 파일 확장자(.html, .egg 등 사용하지 않기)
• 띄어쓰기 하지말고 대신 대쉬( - ) 이용
• 자료 하나당 하나의 url 가지기

등 다양한 점들이 있으니 이에 대해서는 찾아보면 도움이 될것이다.

( 나의 경우에는 외주 백엔드 분과의 소통을 위한 것이므로 너무 자세하게 일일이 들여다보진 않았다 )

 

*엔드포인트(EndPoint)

구글에 What is an API Endpoint? 라고 검색해보면 "An endpoint is one end of a communication channel" 이런 말이 나온다. 

쉽게 말해 커뮤니케이션 채널의 한 쪽 끝에 있는 것이라고 되어있다.

나의 경우 이 자체만으로는 혼동이 왔다.

그러면 www.kakao.com  부터 그 뒤에 오는 모든 것을 다 말하는건가 싶었다.

하지만 정확하게 말하자면 그 뒤에 부분이라고 할 수 있다.

예를 들자면 아래와 같은 형태를 가지는 것이다.

www.{domain_name}.com/{endpoint}

조금 더 다양하게 보자면 아래와 같이 나눠볼 수 있을것이다.

DOMAIN: www.kakao.com
METHODS: GET
ENDPOINT: /posts(리소스)/123123123(파라미터)?contents=고양이장난감(쿼리스트링)

이렇게 나눠보니 보다 확실하게 들어오는 것 같다.

METHODS는 Http Verb인 GET, PUT, POST, DELETE를 말하고, resource는 도메인 리소스를 말한다.

ENDPOINT는 resource + parameter + queryString 을 말하는 것이다.

 

---

이제 필요한 것은 대략적으로 어떤 데이터가 들어가야 할지 정리를 하는 것이다.

외주를 받는 경우 기획서만 보고 만드는 경우가 있다고 들었는데, 프론트단에서 response 값의 data 필드에 어떤 식으로 데이터가 나오면 좋겠다 라고 말을 해보고, 그것을 백엔드 개발자와 조율을 해서 더 좋은 방향으로 맞춰나가는 것이 좋을 것 같다는 조언을 들었다.

 

일을 할 수록 점점 기획서가 얼마나 중요한지를 깨닫게 된다...

 

그렇다면 그 방법은 어떻게 될까?

방법이 다 다를 수 있겠지만, 내가 아는 방법으로는 큰 부분부터 세부적으로 들어가는 것이다.

최초로 사용자 입장에서 서비스를 어떻게 사용할지 전체적인 그림을 알아보는 것이 좋다.

그 대략적인 방식은 위와 같다.

이런 식으로 자신의 사이트에 맞는 방향을 우선 크게 그려보는 것이다.

그 다음은 페이지를 그려본 다음에 페이지 상세목록을 그려보고, 데이터 로직 플로우를 정리하고, 그러면서 필요할만한 데이터를 옆에 적어두는 것이다.

만약 블로그 글과 댓글에 대한 것을 간단하게 짜보자면 위와 같이 해볼 수 있을것이다.

그러면 이를 토대로 각각 서비스별로 이러저러한게 필요하고, 리뷰를 위한 리뷰 데이터, 댓글을 위한 댓글 데이터 등 필요한 것들을 나열을 한다.

 

그 다음 데이터간의 연결성(관계)을 고려하는 것이다.

여기서 프론트엔드에서 작업이 수월해지느냐가 결정 되는 것 같다.

예를 들어 위의 예시처럼 포스트, 댓글 이렇게 데이터가 필요한데, 아무생각 없이 response body를 만들어서 아래와 같이 만들어진다면 이는 프론트단에서 문제를 말할 것이다.

{
  status: 200,
  data: {
    posts: [
      { id: 1, title: "이것이 제목인가", contents: "어쩌고 저쩌고" },
      { id: 2, title: "이것은 제목이다", contents: "어쩌고 저쩌고" },
      { id: 3, title: "이것이 제목이요", contents: "어쩌고 저쩌고" },
    ],
    comments: [
      { id: 1, postId: 3, contents: '댓글달았습니다' },
      { id: 2, postId: 1, contents: '댓글달았습니다' },
      { id: 3, postId: 1, contents: '댓글달았습니다' },
    ]
  }  
},

이러면 post로 맵을 돌리면서 comment에 각각 postId에 해당하는 것들을 골라서 붙여줘야 작업이 가능할 것이다.

그러나 이렇게 만들어놓으면 어떨까?

{
  status: 200,
  data: {
    posts: [
        {
            id: 1, 
            title: "이것이 제목인가", 
            comments: [ ... ] 
        },
        {
            id: 2, 
            title: "이것이 제목이다", 
            comments: [ ... ] 
        },
        {
            id: 3, 
            title: "이것이 제목이요", 
            comments: [ ... ] 
        },
    ]
  }

이렇게 만들어놓았다면 각각 포스트마다 댓글 값을 담아주니까 프론트 단에서 작업하기는 한결 쉬울 것이다.

이런 식으로 서로서로의 관계성을 먼저 생각하고 엮어봐야하는 것도 중요한 점 중 하나이다.

 

---

다음에 미팅을 다녀와보고 또 공부를 해서 포스팅해야겠다...