API 정의

이 문서는 버즈빌의 API(애플리케이션 프로그래밍 인터페이스, Application Programming Interface)를 정의하고 사용하는 방법을 기술한다. 인터페이스는 Protocol Buffers를 통해 정의한다.

가이드라인

API 우선 방식 (API-First Approach)

서비스 구성 시 API 우선 방식을 사용한다. API 우선 방식에서는 서버 혹은 클라이언트 서비스를 개발하기에 앞서 API 를 먼저 구성한다. 이를 통해 각 팀은 병렬적으로 일을 진행할 수 있고, 개발 속도가 빨라지며, API를 더 안정적으로 제공할 수 있다. 자세한 내용은 Understanding the API-First Approach to Building Products 문서를 참고한다.

API 정의

API 레포지토리

buzzapis 레포지토리에서 API를 정의한다. 해당 레포지토리에는 버즈빌 내부 서비스의 API 정의가 모두 포함되어 있다. 프로젝트 구성 및 사용 방법은 프로젝트에 포함되어 있는 README 파일을 참고한다.

API 정의 방법

Protocol Buffers를 통해 API를 정의한다. 자세한 문법은 Protocol Buffers를 참고한다.

Note. 버즈빌에서는 proto3 문법을 사용한다.

API 네이밍 컨벤션

API 네이밍 구성 시 Google Cloud API 네이밍 컨벤션 을 참고한다.

유의 사항

• 패키지 이름은 버젼명으로 끝난다. e.g package buzzvil.library.v1;
• 메소드 이름은 VerbNoun 형태를 따른다.

API 정의 예시

syntax = "proto3";
package buzzvil.library.v1;

service Library {
  rpc GetBook(GetBookRequest) returns (Book) {}
}

message GetBookRequest {
  string id = 1;
}

message Book {
  string title = 1;
  string author = 2;
}

HTTP/JSON API 지원

Protocol Buffers를 통해 gRPC 외에도 HTTP/JSON API를 지원할 수 있다. Googleapis를 활용하여 gRPC Gateway 혹은 Envoy 같은 게이트웨이에서 HTTP 요청을 gRPC 요청으로 변환 가능하다. 자세한 내용은 Transcoding HTTP/JSON to gRPC 문서를 참고한다.

HTTP API 정의

google/api/annotations.proto를 통해 HTTP API를 정의할 수 있다. rpc 정의에 다음 예시와 같은 option을 정의한다. 자세한 문법 및 사용 방법은 Transcoding HTTP/JSON to gRPC 문서와 google/api/http.proto 파일을 참고한다.

syntax = "proto3";
import "google/api/annotations.proto";
package buzzvil.library.v1;

service Library {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
            get: "/v1/books/{id}"
    };
  }
}

API 배포

정의된 API 는 Protocol Buffers와 Swagger 등을 통해 각 언어의 라이브러리로 빌드된다. 빌드된 라이브러리는 각 언어별 패키지 관리 시스템(Package management system)으로 배포된다.

패키지 정보

각 API 의 패키지 정보는 해당 API 폴더의 package.json 파일로 관리된다. name 과 version 필드는 필수 사항이며, 그 외 추가 정보들이 담길 수 있다. version 정보는 최초 생성 시점 외에는 직접 수정하지 않는다. 해당 정보는 master 브랜치 병합 시점에 풀 리퀘스트(Pull Request) 정보를 바탕으로 자동으로 설정된다.

package.json 예시

{
    "name": "book",
    "version": "0.1.0",
    "description": "Book service provides library data."
}

패키지 관리 시스템

Go

Go API 라이브러리는 github.com을 패키지 관리 시스템으로 사용한다. 빌드 시점에 buzzapis 레포지토리 내부에 빌드된 Go API 파일이 첨부된다. 자세한 사용법은 Go 프로젝트 문서를 참고한다.

Python

Python API 라이브러리는 버즈빌 내부에서 사용하는 PyPI를 통해 관리한다. 자세한 사용법은 Python 프로젝트 문서를 참고한다.

Java

Java API 라이브러리는 Bintray를 통해 관리한다. Java 라이브러리는 gRPC 와 HTTP 라이브러리로 각각 빌드되어 배포된다. 자세한 사용법은 Java 프로젝트 문서를 참고한다.