REST API 디자인 가이드 적용기

아주 작은 시스템을 개발할 때는 API들이 약간 엉켜 있어도 

문제가 생겼을때 원인을 찾는데 어렵지 않을 것이다.

하지만 시스템이 커지고 복잡 하다면, 서로의 인터페이스를 잘 정돈하고 관리하는 것이 중요해진다.

구글이나 페이스북 등 큰 기업들은 잘 정돈하고자 그들만의 REST API 가이드라인을 가지고 있다.

https://cloud.google.com/apis/design/resources?hl=ko

나는 여러 개발자들과 함께 REST API 개발을 담당하게 되었다.

그래서, 구체적인 개발을 시작 하기 전에 사내 REST API 디자인 가이드를 만들어야겠다고 마음을 먹었다.

가이드라인을 만들고 이것을 참고해 반년 정도 개발-운영을 했다.

처음 가이드라인을 만들때 했던 고민과 챙겨야할 것들, 

그리고 가이드라인과 함께 개발하면서 느낀점들을 정리해보고자 한다.

REST API를 쓰는 이유

REST API 에 대한 설명은 인터넷에 많다보니 생략하려고 한다.

  REST

  https://brainbackdoor.tistory.com/53

  API

  https://medium.com/@dydrlaks/api-%EB%9E%80-c0fd6222d34c

핵심은 표현에 대한 약속

원하는 결과는 얻을 수 있는 "표현에 대한 약속"은 종류가 많을 것이다. 

하지만 이것들은 좋은 약속도 있고 안좋은 약속도 있다.

안좋은 약속은 당장에 동작에 문제가 없더라도, 

나중에 가면 유지보수가 힘들어지거나 구조를 더 꼬이게 만드는 것들을 말한다.

좋은 약속에 해당하는 "표현에 대한 약속"들을 모아.. RESTful API 라고 부르고 있다고, 나는 생각한다.

  

디자인가이드의 필요성

협업

여러 개발자들이 여러가지 각자의 자원에 대해 개발을 할 때 필요하다. 

개발자가 많고 자원이 많은 상황에서 일일이 해당 자원의 개발자를 찾아가 API를 이해하는것은 시간 낭비가 크지만, 가이드라인에 따라 개발 되었다면 이 낭비를 줄일 수 있다.

개발 효율

위의 협업과 비슷하다. 자원에 대한 통일된 접근 방식은 개발 효율 을 높인다.

API를 만드는 사람 입장에서 가이드라인에 맞게만 만들면 되기 때문에 고민할 필요가 적어진다.

API를 사용하는 사람 입장에서도 동일하게 효율적으로 API를 이해할 수 있게 되어 좋다.

기능 단순화

API에서 표현해야 하는 자원의 범위는 중요한 문제다. 가이드라인에는 자원의 범위에 대한 내용을 다루어야 하고, 개발자들도 이것에 맞추어 개발해야 효율성이 높아진다.

간혹 자원에 대한 범위나 접근 방법을 정하기 애매할 때가 있다. 

나도 모르게 여러가지 자원을 한번에 묶어서 처리하거나,

필요 이상으로 여러가지 기능을 한번에 묶어서 처리하는 식으로 개발하게 될 수 있다.

이렇게 되면 API(ex. 엔드포인트)는 기능에 의존도가 높아져서 다양한 용도로 활용이 어렵게 된다.

예를 들어 사용자정보, 사용자부가정보 라는 자원이 있다고 하자. 

이것을 1가지 자원으로 묶어서 표현을 하게되면, 사용자정보만 필요한 상황이 왔을때 이 자원은 사용자정보+사용자부가정보 로 묶여 있어서 필요하지 않은 자원도 가져가야 한다.

API 범위가 크면 사용할 필요 없는 자원도 가져가야 할 경우가 많아질 것이다. 

그렇다고 범위가 너무 작으면 API 호출이 많아 지게 된다.

MSA 구조 관련된 이슈로 볼 수도 있다. 

경험상 가급적 자원 범위를 작게 유지하는 편이 나중에 추가기능이 필요할 때 더 유연하게 대처할수 있다.

그래서 디자인가이드에 이런 내용을 담아 약속하면 좋다.

 

디자인가이드 필수요소

나는 구글의 가이드라인을 많이 참조했다. 

바퀴를 다시 발명하고 싶은게 아니라면..앞서간 개발자들의 지식을 누리는건 좋은일이다.

시작부터 잘못되면 나중에 이도저도 안되서 후회할 수도 있다.

구글의 가이드라인은 양이 방대하다. 때문에 그대로 적용 했다가는 구성원들에게 버림 받을 수 있다.

나는 적당한 선에서 타협을 하고 개발하면서 규칙을 추가해 나가기로 정하였다.

아래는 REST API 가이드라인을 만들면서 처음에 정했던 규칙들이다.

 

URL 규칙

URL을 만들때 아래 규칙에 따라 만든다.

https://[서버주소]/[버전]/[자원명]/[ID]

https://localhost/v1.0/articles/1

• 자원명은 반드시 명사로 표시해야 한다. 

• 자원명은 복수로 표시해야 한다.

게시판에 대한 자원명 이라면 "게시물들(articles)" 로 정해야한다.

자원명은 자원에 대한 복수 명사 가 되어야 한다.

아래 예시들처럼 어떠한 행동이나 조건을 포함하면 안된다.

"게시판조회하기(boardView)","게시판최근게시물(boardNewView)","게시판모아보기(boardAllView)"

• 페이징 처리가 필요할 때는 offset 과 limit 을 사용한다

/articles?offset=0&limit=20

• 계산, 변환 등 어쩔수 없이 URL 에 동사를 사용해야 하는 케이스는 자원명 뒤에 콜론(:)을 넣고 뒤에 동사를 붙인다.

/articles:backup

Http Method 기능 정의

주로 사용하는 Http Method 는 GET, POST, PUT, DELETE 4가지가 있다.

앞에서 정한 URL(자원명)에 이 4가지 행동의 조합으로 모든 요청을 받아서 처리해야 한다.

• POST : 새로운 자원 생성
• GET : 자원의 목록 혹은 단건 가져오기
• PUT : 기존의 자원 업데이트
• DELETE : 기존의 자원 삭제

버전 관리

버전은 v[메이저].[마이너] 로 구성한다.

• 메이저 : API의 변경이 이전 버전과 호환이 되지 않는 수준의 변경
• 마이너 : 호환 가능한 수준의 변경

이 규칙들과 함께 요청(request)의 표준 표현, 응답(response)의 표준 표현, 에러응답의 표준 표현을 정하고 추가해서 우리 조직만의 REST API 가이드라인을 만들어 사용하였다.

디자인 가이드 운영하며 느낀점

가이드라인을 처음 만드는 것은 그리 어려운 일은 아니었다.

제일 어려운점은 계속해서 가이드라인을 지키는것이다.

가이드라인이 처음 만들었을 때는 잘 지켜나갔다. 

하지만 시간이 지나고 일정이 바빠질 때가 위험한 순간이다. 

이럴때 가이드라인 만으로 해결할 수 없는 예외가 생기면, 

가이드라인을 조금 벗어나더라도 일단은 동작하는 방향으로 개발을 완료하는 경향이 생겨났다.

  

예외가 생겼다면 2가지 케이스중 하나일 것이다.

• 가이드라인을 잘못 이해해서 생긴 예외
• 기존 가이드라인에서 해결할수 없어서 추가 규칙이 필요한 예외

잘못 이해한것이라면 좀 더 고민해서 자원을 나누고 표현방법을 바꾸면 될것이다.

규칙의 추가나 변경이 필요하다면, 구성원들과 충분히 논의하고 결정하면 된다.

  

이 두가지 과정이 꼭 필요하다.

처음부터 완벽한 가이드라인은 있을 수 없다. 

또한 조직이나 업무에 따라 필요한 가이드라인은 다를 것이다.

그렇기 때문에..

계속해서 의문을 제기하고, 구성원간의 논의-결정들이 가이드라인에 쌓이는 것이 중요하다.

그래야 좋은 가이드라인을 만들수 있고, 시스템의 품질을 올리는데 도움이 될 거라고 생각한다.

  

제일 중요한것은 구성원 모두가 이해하고, 도움이 된다는 확신과 개선해 나가려고 하는 의지라고 생각한다.

하지만 역시 쉽지 않은 일이다. 

잊혀지지 않으려고 주기적으로 강조를 해야했고 앞으로도 계속 그래야 할 것으로 보인다.