API 개발에서 IDL이 중요한 이유

우리는 API 시대에 있으며 우리의 서비스는 API에 노출됩니다. 새로운 비즈니스 요구 사항이 발생하면 컨텍스트 스토밍이 발생하고 기능은 DDD 원칙으로 정의되고 API 형식으로 구현됩니다. 백엔드 개발자는 API 계약을 설계하고 프런트엔드 동료와 공유하여 작업을 시작합니다. 프론트엔드 개발자 또는 다른 팀에서 API 계약에 따라 기능을 설계합니다. 즉, 범위에 있는 모든 사람이 독립적으로 작업하고 병렬로 작업을 시작할 수 있도록 API 계약의 견고한 기반에서 작업해야 합니다.

이 문서는 우리가 매일 직면하는 API 연락처 공유 문제와 API 설계, 공유 및 개발 방식을 변경하여 생산성을 향상시키는 방법을 재고해야 하는 이유에 대해 설명합니다.

RPC 대 평안한

REST(Representational State Transfer) 스타일은 분산 하이퍼미디어 시스템 내의 아키텍처 요소를 추상화한 것입니다. - 로이 토마스 필딩.

RESTful API는 API 클라이언트가 API 서비스에서 요구할 수 있는 리소스에 중점을 둡니다. 리소스 기반이며 일반적으로 리소스 끝점에서 CRUD 작업을 수행합니다. 일반적인 RESTful API는 일반적으로 다음과 같습니다.

POST /users/501/messages HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"message": "Hello!"}

Contrast에서 RPC API는 get 및 post 기능만 있는 작업 기반입니다.

POST /SendUserMessage HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"userId": 501, "message": "Hello!"}

In Contrast, RPC API is action based, which only have *get* and *post* functions.

RESTful을 사용하여 RPC를 교체하시겠습니까?

다음 예제를 검토하여 좋은 솔루션인지 확인하십시오.

RESTful 접근법

제목 상태를 처리해야 하는 라이브러리 시스템을 개발한다고 상상해 보십시오. 도서관 관리자가 틸트 상태를 업데이트해야 하는 경우 아래와 같은 API를 제공할 수 있습니다.

POST /titles/123/in

POST /titles/123/out

POST /titles/123/suspended

`shell
PATCH /titles/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"status": "Out"}

`

There is a problem that you want to update mutilple titles in batch and want to add background logic when you update a specific status. For example, when you want to set a title to state of "In" and notify all the readers that are in the wating list.

RPC 접근법

You can design your API with action based RPC Post function.

`
POST /api/titles.transition_state HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
"title": "123",
"status": "Out",
"user": "U123,U234"
}

`

By examples above, you can clearly see the benefits to design you API contract in a hybrid way. For resources, you can expose RESTful API to allow your API consumers to perform CRUD actions, and for the cases that requires background logic and data manapulation, the RPC approach is a better solution.

IDL이 중요한 이유

Now, let`s consider how to define a API contract. IDL (Interface Definition Language) is a must for developers to share the API specification. There are multiple reasons including:

1. IDL can be used to generate code artifacts.
2. IDL has no ambiguity.
3. IDL can be better managed in a VSC system (Github is my favorite).

I recommend protobuf as our IDL to define the API contract for reasons:

1. Protobuf can be used to generate the OpenAPI specification, whereas the OpenAPI cannot be used reversely.
2. Protobuf is widely used in the most popular RPC framework gRPC, which is actively developed and maitained by Google and community.