2017. 3. 11.

Google API 설계의 사상을 담은 Google의 API Design Guide

저에게 있어 클래스의 이름을 짓거나 메소드의 이름을 만든다거나 변수 이름을 생각하는 것은 언제나 도전하고 고민해야 하는 일 중의 하나입니다. 도메인 객체의 경우는 그나마 사전에 팀 내에서 또는 기획자와 또는 현업 분들과 이야기를 진행하는 과정에서 결정되거나 일반적인 관습 같은 것을 따라서 고민 없이 결정하는 경우도 많지만 말이죠.
Rest API를 설계하는 것도 역시나 같은 의미에서 저에게는 참 힘든 일인 경우가 많습니다. 물론 도메인 이름을 리소스 이름으로 사용하고 거기에 일반적인 Rest API 설계 규칙에 따라서 GET/POST/PUT/DELETE 메소드에 따라 적당한 규칙을 정해서 생각 없이 가는 경우가 대부분이지만, 아주 가끔 Custom API를 만들어야 하는 경우에는 어떤 게 좋을지 고민하게 되더군요.
아마도 기초가 부족하고 생각만 많은 성격이라 그런가 봅니다.

그러다 보니 평소 시간이 날 때 다른 사람들의 소스나 설계를 보는 것을 좀 즐기는 편인데요.
언제 공개가 되었는지는 정확히 모르겠지만, Google의 Cloud API를 설계할 때 사용한 Design Guide가 공개가 되어있더군요.

전문은 https://cloud.google.com/apis/design/ 에서 확인할 수 있습니다.

전체를 아직 다 읽지는 않았지만, 내용에는 Rest API와 구글의 Protocol Buffer를 이용한 gRpc에 사용한 Design Guide도 함께 정리되어 있는 것으로 보입니다.

한글 번역문도 있으면 좋았겠습니다만, 아직 영문만 있는 것으로 보이네요.

RPC 디자인을 해야 하는 경우는 거의 없어서 우선 Rest API 관련 가이드만 조금 살펴보았는데 특히 그중에서 Restful Design Flow와 Handling Errors에 대한 내용만 이곳에 간단히 정리를 해 볼까 합니다.

그 외에도 리소스 이름 명명법이라던가 일반 또는 커스텀 메소드에 대한 정의 방법, 네이밍 규칙, 디자인 패턴, 도큐멘테이션, 버전 정의 방법 등의 여러 가지에 대한 가이드가 있습니다.

평소 내가 만든 API의 디자인이 잘 된 것인지 어떤지 또는 API 디자인에 대해서 실례를 통한 공부를 해보고 싶으신 분은 어느 정도 참고가 될 것 같습니다.


Restful Design Flow


  • API가 제공하는 리소스의 유형 결정(Determine what types of resources an API provides).
  • 리소스간의 관계 결정(Determine the relationships between resources).
  • 리소스의 유형과 관계를 기반으로 리소스 이름의 스키마를 결정(Decide the resource name schemes based on types and relationships).
  • 리소스 스키마를 결정(Decide the resource schemas).
  • 최소한의 메소드를 리소스에 첨부(Attach minimum set of methods to resources).

좀 당연한 플로우라 설명은 생략합니다. 다만, 평소 API 디자인할 때 위와 같은 플로우로 생각하지 않고 생각 없이 진행하는 경우가 많아서 한 번 정리해봤습니다.

Handling Errors


  • 200 OK
  • 400 INVALID_ARGUMENT
  • 400 FAILED_PRECONDITION
  • 400 OUT_OF_RANGE (Client specified an invalid range)
  • 401 UNAUTHENTICATED
  • 403 PERMISSION_DENIED
  • 404 NOT_FOUND
  • 409 ABORTED (Concurrency conflict, such as read-modify-write conflict)
  • 409 ALREADY_EXISTS (The resource that a client tried to create already exists)
  • 429 RESOURCE_EXHAUSTED (Either out of resource quota or reaching rate limiting)
  • 499 CANCELLED (Request cancelled by the client)
  • 500 DATA_LOSS
  • 500 UNKNOWN
  • 500 INTERNAL
  • 501 NOT_IMPLEMENTED
  • 503 UNAVAILABLE (Service unavailable. Typically the server is down)
  • 504 DEADLINE_EXCEEDED 
Error Code 의 경우는 Spring의 HttpStatus 문서와 비교해 보니 좀 더 흥미롭네요. 참고로 문서에 정의되어있는 HttpStatus Code는 아마도 IANA의 Hypertext Transfer Protocol (HTTP) Status Code Registry를 기반으로 한 것으로 보입니다. 즉 일반적인 코드 정의라는 말이죠. (잠시 링크를 넣기 위해서 아는척했습니다. 죄송합니다.)
대부분 구글의 Error Code도 같습니다. Rest API 디자인에 있어서 가장 기본적인 원칙 중 하나가 HttpStatus Code를 이용해서 Error Code를 정의하라는 것이니 어쩌면 당연해 보입니다. 다만, 400 BAD_REQUEST, 409 CONFLICT, 500 INTERNAL_SERVER_ERROR 등의 세분화 및 확장의 모습은 어떻게 HttpStatusz Code를 이용해서 에러를 정의할까에 대한 기본 규칙을 보여줍니다. 그리고, 499 CANCELLED 에서는 UNASSIGNED 되어있는 코드를 이용해서 확장하는 방법에 대한 예도 보여주네요. 아마도 서버 에러가 아닌 요청과 관련된 에러 대부분을 정의하는 400대에서 UNASSIGN 되어있는 가장 마지막 번호를 이용한 게 아닌가 싶습니다.

한번에 전부를 읽는 것도 좋겠지만, 가끔 생각날 때마다 필요한 부분을 참고하는 용도로 사용하면 좋은 자료가 아닐까 생각합니다.




2017. 3. 5.

[TED Talk 소개] 시간이 없다는 것은 우선순위가 낮다는 것이다.

간만에 TED Talk 을 봤습니다.

시간 관리에 관한 짤막하지만 아주 강렬한 강의였습니다.

평소 다른 탓을 하거나 변명하는 것을 별로 좋아하지 않습니다. 그중에서 가장 하기 싫은 변명인데 가장 많이 하는 변명이 시간이 없다는 것이죠. (이 블로그 글에도 시간이 없다고 쓴 적이 있는듯하네요)

이 TED 동영상은 Laura Vanderkam 이라는 분이 시간 관리에 대해서 강연한 12분 남짓의 짧은 내용입니다. 잠시 구글링을 해보니 이 분은 주로 시간 관리를 바탕으로 한 성공학 관련 강연을 하시고 관련 책을 집필하시는 분인 것으로 보이네요. 국내에는 "시간 창조자 : 똑같이 주어진 시간, 그러나 다르게 사는 사람들(원제: 168 Hours)"이라는 책이 2011년에 번역 출간되어있더군요.



이 TED 동영상의 내용을 요약하자면 매우 단순합니다. (TED 동영상의 가장 큰 장점이지요)

중요하게 생각하는 즉 우선순위가 높은 일들을 미리 스케줄에 넣어놓고 이것을 하기 위한 시간을 만들라는 내용입니다. 그러기 위해서 두가지 정도를 이야기하는데 내년성과 평가를 지금 해 보라는 것과 다음주의 할일을 미리 정하고 그에 맞춰서 시간을 만들어 넣으라는 내용입니다.

주로 시간관리와 관련된 자기계발서나 글을 많이 읽으신 분들은 "맨날 하는 뻔한 이야기"라고 생각하실지도 모르겠네요.

이 동영상에서는 이런 예를 통해서 설명합니다.
작은 회사를 운영하시는 아이 6을 가지신 어떤 여성분이(이 TED가 아마도 여성분들을 위한 것이었나 봅니다. 관중분들이 모두 여성분들이시더군요) 어느 날 퇴근해서 보니 배관이 터졌답니다. 매우 중대한 사태였기 때문에 다음날에는 배관공을 불러서 고치고 그다음 날에는 카펫 청소업체를 부르는 등의 조치를 해서 빠르게 문제를 해결했다고 합니다. 그분은 이 처리를 하기 위해서 일주일간 7시간을 투자하셨는데, 이분에게 운동을 위해 7시간을 투자하라고 하면 시간이 없다고 하리라는 것이죠. 아주 바쁜 와중에도 중요한 일이었기 때문에 7시간을 만들어냈다는 말입니다.

누구에게나 주당 168시간이 주어지고 일주일에 잔업을 포함해서 50시간을 근무하고 56시간을 잠을 잔다고 해도 62시간이 주어집니다. 시간이 없다는 것은 우선순위가 낮다는 말이니까 제가 평소 많이 하는 시간이 없다는 변명을 결국 그만큼 우선순위를 가진 중요한 일은 아니라고 말하는 것이 되겠네요.

제발 제 지인분들은 이 글 보지 말아주세요. 혹시 보시더라도 오해하지 마세요. 결코, 우선순위가 낮지 않습니다. 단지 제가 시간 관리를 잘 못 하다 보니 다른 급한 일들에 밀려서 그런 것 뿐입니다. 하하하..

앞으로는 중요하지 않지만 급한 일들을 처리하느라 또는 중요하지도 급하지도 않은 일들을 처리하느라 시간을 낭비하지 말고 중요한 일 위주로 시간을 배분해야겠네요. 그래서 소중한 분들과 소주 한 잔 기울일 수 있는 시간을 많이 가져봐야겠습니다.