API 설계 개요

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

설계 단계에서는 API의 요구사항을 정의합니다. API 디자이너는 소비자에게 노출할 서비스를 계획하고 이러한 서비스에 액세스하도록 API를 설계합니다. API 요구사항을 캡처하려면 다음 문서 중 하나를 만듭니다.

  • OpenAPI 문서
  • GraphQL 스키마

다음 섹션에서는 OpenAPI 및 GraphQL 문서와 API의 수명 주기에서 이들의 역할을 자세히 설명합니다. 두 API 설계 옵션을 비교하려면 이 블로그 게시물의 REST 및 GraphQL 비교를 참조하세요.

OpenAPI 사양이란 무엇인가요?


"OpenAPI Initiative(OAI)는 Swagger 사양에 따라 공급업체 중립적인 API 설명 형식을 생성, 진화, 홍보하는 데 중점을 두고 있습니다." OpenAPI Initiative에 대한 자세한 내용은 https://openapis.org를 참조하세요.

OpenAPI 문서에서는 표준 형식을 사용하여 RESTful API를 설명합니다. JSON 또는 YAML 형식으로 작성된 OpenAPI 문서를 머신에서 읽을 수 있지만 사람도 쉽게 읽고 이해할 수 있습니다. OpenAPI 사양은 기본 경로, 경로 및 동사, 헤더, 쿼리 매개변수, 콘텐츠 유형, 응답 모델 등과 같은 API 요소에 대한 공식 설명을 사용 설정합니다. 또한 OpenAPI 문서는 일반적으로 API 문서를 생성하는 데 사용됩니다.

다음은 Apigee의 간단한 Hello World 샘플을 설명하는 OpenAPI 문서의 프래그먼트입니다. 자세한 내용은 GitHub의 OpenAPI 사양을 참조하세요.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

OpenAPI 사양에 대해서는 여러 가지 뛰어난 정보 출처가 존재합니다. 처음에는 OpenAPI 사양의 개요, 블로그, 링크를 찾을 수 있는 OpenAPI Initiative 사이트에서 시작하는 것이 좋습니다. 스키마 요소와 데이터 유형에 대한 자세한 설명은 사양을 참조하세요.

OpenAPI 사양 저장소에서 다운로드할 수 있는 다양한 JSON 및 YAML 예시 OpenAPI 문서가 있습니다.

GraphQL 스키마란 무엇인가요?

GraphQL 스키마는 클라이언트에서 쿼리할 수 있도록 API에 제공되는 데이터를 설명합니다.

GraphQL 사용 시 이점은 다음과 같습니다.

  • 단일 엔드포인트에서 지정된 작업의 모든 필드에 액세스할 수 있습니다.
  • 스키마 정의 언어라고 하는 강력한 쿼리 언어를 사용 설정하면 필요한 데이터에 정확하게 액세스하여 데이터를 과도하게 가져오거나 부족하게 가져오는 것을 방지할 수 있습니다.
  • 쿼리 처리는 동시에 수행됩니다.

GraphQL에 대한 자세한 내용은 graphql.org를 참조하세요.

다음은 데이터 진입점(쿼리 유형), 사용 가능한 쓰기 작업(변형 유형), 데이터 유형을 정의하는 GraphQL 스키마의 예시입니다.

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

GraphQL 스키마를 쿼리하여 필요한 데이터를 정확하게 JSON 페이로드로 반환할 수 있습니다.

GraphQL 쿼리 및 결과

문서를 수정하면 어떻게 되나요?

각 OpenAPI 또는 GraphQL 문서는 API 수명 주기 전반에서 정보 소스 역할을 합니다. 개발부터 게시, 모니터링에 이르기까지 API 수명 주기의 각 단계에서 동일한 문서가 사용됩니다.

문서를 수정하거나 삭제하면 아래로 내려가며 영향을 미칩니다.

  • 문서를 수정하면 API 프록시와 리소스를 노출하는 API 제품을 포함한 관련 아티팩트를 수동으로 수정하고 API 참조 문서를 다시 생성하여 문서에 구현된 변경사항을 반영해야 합니다.
  • 문서를 삭제하면 API 프록시를 포함하여 관련 아티팩트를 수동으로 삭제하고 관련 리소스를 삭제하도록 API 제품을 수정하며 API 참조 문서를 다시 생성하여 문서와 해당 리소스 삭제를 반영해야 합니다

OpenAPI 문서에서 API 프록시를 만들면 어떻게 되나요?

Edge에서는 OpenAPI 문서에서 API 프록시를 만들 수 있습니다. 몇 번의 클릭만으로 경로, 매개변수, 조건부 흐름, 대상 엔드포인트가 자동으로 생성된 API 프록시가 표시됩니다. 그런 다음 OAuth 보안, 비율 제한, 캐싱과 같은 기능을 추가할 수 있습니다.

다음 섹션에 설명된 대로 OpenAPI 문서에서 API 프록시를 만들 수 있습니다.

API를 게시하면 OpenAPI 문서의 스냅샷을 사용하여 API 참조 문서를 생성합니다. 이 스냅샷은 사양 저장소에 있는 설명 문서의 특정 버전을 나타냅니다.