External Services: Define an API Specification for an External Service

Admin Intermediate > External Services > Define an API Specification for an External Service

이번시간에는 API Specification을 정의하는 방법에 대해서 설명드리도록 하겠습니다. 양식은 JSON이나 YAML로 쓰여지는데 우리는 JSON으로 사용된 것을 기준으로 설명드리도록 하겠습니다.

지난시간에 API Spec의 예제를 보여드렸는데 전체양식은 생략하고 기능정의하는 부분만 좀더 보강해서 자세히 보도록 해볼게요. 상대경로 별로 GET, POST, PUT, DELETE이렇게 4가지 방법으로 API를 호출합니다. 각 Method별 설명은 아래와 같습니다.

Operations for path: /accounts/{accountName}	Description
GET	account 조회
POST	account 생성
PUT	account 갱신
DELETE	account 삭제

API Spec의 “paths”부분 밑으로 API Endpoint를 정의합니다. 그리고 그 밑으로 Method들을 나열하고 각 Method별로 입력값과 출력값을 정의합니다. 그중에 GET Method하나만 자세히 좀 보자면요.

"paths": {
    "/accounts/{accountName}": {            << 이게 상대경로
      "get": {                              << 이게 Method
        "operationId": "getAccount",        << 함수명
        "summary": "Retrieves an account",  << 짧은 설명
        "description": "Retrieves the account with specific name",<< 긴설명
        "consumes": ["text/plain"],         << 호출받을때 문서형식
        "produces": ["application/json"],   << 응답할때 문서형식
        "parameters": [                     << 검색필터
          {
            "name": "accountName",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "Name of the account"
          }
        ],
        "responses": {                       << 응답코드
          "200": {                           << 200 문제없을때
            "description": "The response when system finds an account with given name",
            "schema": {                     << 결과스키마는 accountDetails에
               "$ref": "#/definitions/accountDetails"
            }
          },
        "400": {                             << 400 입력값에 문제있으때
          "description": "Error response if the account name parameter is less than minimum characters",
          "schema": {
            "$ref": "#/definitions/errorModel"
          }
        },
        "404": {                              << 404 결과없을때
          "description": "Error response if the account is not supported by service or account is not found",
          "schema": {
            "$ref": "#/definitions/errorModel"
          }
        }
      }
    }
  }
}

Quiz

1. What is an API spec?
   A. A human-readable file that External Services consumes to generate invocable actions.
   B. A human-readable file that a flow creates for the parameters needed in the definition when your flow runs.
   C. A human-readable file definition that a flow outputs at the end of a flow interview.
   D. A machine-readable external service that must be compiled.
2. Which of these schemas is valid to use with External Services?
   A. The schema includes POST methods and a GET method with an empty request body.
   B. The schema includes a form parameter and properties without values.
   C. The schema adheres to OpenAPI specification and includes parameters with names.
   D. The schema has less than 100,000 characters and includes response headers.