API-First Approach with Protocol Buffers

API 우선 방법이란 서버와 클라이언트 서비스를 개발하기 전에 API를 먼저 구상하는 방법이다.

API-First Approach에 대해 (정말 정말 정말)간단하게 소개하려고 한다. 더 자세하게 알고 싶은 분들은 하단에 참조 문서들을 확인하면 좋을 것 같다.

장점
- 개발 속도 향상
  - 서버와 클라이언트를 개발하는 팀이 각각 병렬적으로 일을 진행할 수 있다.
  - 설정된 API 정의를 기반으로 구현하기 때문에 API가 업데이트, 릴리즈될 때까지 기다릴 필요가 없다.
- 안정적인 API 제공
  - API-First는 일관(강력한 종속성)되게 각 서비스에 제공함으로서 개발자 이슈로 인한 에러 발생이 줄어들 수 있다.
- 더 다양한 장점의 설명은 여기에

API 정의 방법

프로토콜 버퍼를 통해 API를 정의할 수 있다.

예시) gRPC

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
syntax = "proto3";
package sellmate.user.v1

service User{
	rpc CreateUser(CreateUserRequest) returns (CreateuserResponse) {}
}

message CreateUserRequest{
	User user = 1;
}

message CreateuserResponse{
	bool success = 1;
}

message User{
	string id = 1;
  string name = 2;
  string password = 3;
  optional int createdAt = 4;
}

HTTP API도 정의할 수 있다

google/api/annotations.proto

예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
syntax = "proto3";
import "google/api/annotations.proto";
package sellmate.user.v1

service User{
	rpc CreateUser(CreateUserRequest) returns (CreateuserResponse) {
		option (google.api.http) = {
			post: "/v1/user"
      body: "*"
		}
	}
}

배포
- 정의된 proto파일들은 각 언어에 맞게 빌드할 수 있다.
- dart 빌드 예시
  1
  protoc -I=$SRC_DIR --dart_out=$DST_DIR $SRC_DIR/*.proto
- php 빌드 예시
  1
  protoc --proto_path=src --php_out=build/gen src/*.proto
- generate된 정의서로 각 프로젝트에서 종속적으로 API생성 및 사용할 수 있다.
문서
- 정의된 API는 직접 코드를 보는 방법도 있지만, UI로도 확인할 수 있다.
  - buf.build
    - 작년에 유료로 전환되었다(꽤 비쌈).
    - git에 배포하지 않고 buf.build에 배포하여 사용할 수 있으며 UI상으로 상세하게 문서를 확인할 수 있다.
  - swagger
    - swagger_out 옵션을 통해서 swagger.json파일을 생성할 수 있다.
    - 참고

참고

https://swagger.io/resources/articles/adopting-an-api-first-approach/

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

https://cloud.google.com/endpoints/docs/grpc/transcoding?hl=ko

https://protobuf.dev/getting-started

https://github.com/co3k/protobuf-swagger-example/tree/master

API-First Approach with Protocol Buffers#

API-First Approach with Protocol Buffers