저에게 있어 클래스의 이름을 짓거나 메소드의 이름을 만든다거나 변수 이름을 생각하는 것은 언제나 도전하고 고민해야 하는 일 중의 하나입니다. 도메인 객체의 경우는 그나마 사전에 팀 내에서 또는 기획자와 또는 현업 분들과 이야기를 진행하는 과정에서 결정되거나 일반적인 관습 같은 것을 따라서 고민 없이 결정하는 경우도 많지만 말이죠.
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 디자인에 대해서 실례를 통한 공부를 해보고 싶으신 분은 어느 정도 참고가 될 것 같습니다.
좀 당연한 플로우라 설명은 생략합니다. 다만, 평소 API 디자인할 때 위와 같은 플로우로 생각하지 않고 생각 없이 진행하는 경우가 많아서 한 번 정리해봤습니다.
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 되어있는 가장 마지막 번호를 이용한 게 아닌가 싶습니다.
한번에 전부를 읽는 것도 좋겠지만, 가끔 생각날 때마다 필요한 부분을 참고하는 용도로 사용하면 좋은 자료가 아닐까 생각합니다.
댓글
댓글 쓰기