Omówienie projektowania interfejsów API

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Na etapie projektowania określasz wymagania dla interfejsu API. Jako projektant interfejsów API planujesz usługi, które chcesz udostępnić konsumentom, i projektujesz interfejsy API umożliwiające dostęp do tych usług. Aby określić wymagania interfejsu API, tworzysz jeden z tych dokumentów:

  • Dokument OpenAPI
  • Schemat GraphQL

Poniższe sekcje zawierają więcej informacji na temat dokumentów OpenAPI i GraphQL oraz ich roli w cyklu życia interfejsu API. Porównanie 2 opcji projektowania interfejsu API znajdziesz w materiałach REST i GraphQL w tym poście na blogu.

Czym jest specyfikacja OpenAPI?


„OpenAPI Initiative (OAI) koncentruje się na tworzeniu, rozwijaniu i promowaniu neutralnego dla dostawcy formatu opisu interfejsu API opartego na specyfikacji Swagger”. Więcej informacji o inicjatywie OpenAPI znajdziesz na stronie https://openapis.org.

Dokument OpenAPI wykorzystuje standardowy format do opisywania interfejsu API REST. Dokument OpenAPI napisany w formacie JSON lub YAML jest zrozumiały dla maszyn, a dodatkowo czytelny dla ludzi. Specyfikacja OpenAPI umożliwia formalny opis elementów interfejsu API, takich jak ścieżka bazowa, ścieżki i czasowniki, nagłówki, parametry zapytań, typy treści, modele odpowiedzi i inne. Oprócz tego dokument w standardzie OpenAPI jest często używany do generowania dokumentacji interfejsów API.

Oto fragment dokumentu OpenAPI opisującego prosty przykład hello world w Apigee. Więcej informacji znajdziesz w specyfikacji OpenAPI na GitHub.

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
...

Istnieje wiele doskonałych źródeł informacji na temat specyfikacji OpenAPI. Warto zacząć od witryny OpenAPI Initiative, w której znajdziesz przeglądy, blogi i linki do specyfikacji OpenAPI. Szczegółowe opisy elementów schematu i typów danych znajdziesz w specyfikacji.

Jest wiele przykładowych dokumentów OpenAPI w formacie JSON i YAML, które możesz pobrać z repozytorium OpenAPI Specification.

Co to jest schemat GraphQL?

Schemat GraphQL opisuje dane dostępne w Twoim interfejsie API, do których klient może wysyłać zapytania.

Zalety korzystania z GrafQL:

  • Jeden punkt końcowy zapewnia dostęp do wszystkich pól w ramach danej operacji
  • Zaawansowany język zapytań, nazywany Schema Definition Language, pozwala uzyskać dostęp do dokładnie tych danych, których potrzebujesz, zapobiegając nadmiernemu lub niedostatecznemu pobieraniu danych.
  • Przetwarzanie zapytań odbywa się równolegle

Więcej informacji o GraphQL znajdziesz na graphql.org.

Poniżej znajdziesz przykład schematu w GraphQL, który określa punkt wejścia danych (typ zapytania), dostępne operacje zapisu (typ modyfikacji) i typy danych.

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!
}

Możesz przesłać zapytanie do schematu GraphQL, aby zwrócić dokładnie te dane, których potrzebujesz w postaci ładunku JSON.

Zapytanie i wyniki w GraphQL

Co się stanie, jeśli zmodyfikuję dokument?

Każdy dokument OpenAPI lub GraphQL pełni rolę źródła wiarygodnych danych przez cały cykl życia interfejsu API. Ten sam dokument jest używany na każdym etapie cyklu życia interfejsu API – od programowania, przez publikowanie, po monitorowanie.

Gdy edytujesz lub usuwasz dokument, wpływa to na poszczególne elementy:

  • Jeśli edytujesz dokument, musisz ręcznie zmodyfikować powiązane artefakty, w tym serwer proxy interfejsu API i wszelkie usługi API, które ujawniają jego zasoby, a także ponownie wygenerować dokumentację referencyjną interfejsu API, aby odzwierciedlić zmiany wprowadzone w dokumencie.
  • Jeśli usuniesz dokument, musisz ręcznie usunąć powiązane artefakty, w tym serwer proxy interfejsu API, i edytować usługi API, aby usunąć powiązane zasoby. Następnie musisz ponownie wygenerować dokumentację referencyjną interfejsu API, aby odzwierciedlić usunięcie dokumentu i jego zasobów.

Co się stanie, gdy utworzę serwer proxy interfejsu API na podstawie dokumentu OpenAPI?

W Edge możesz tworzyć serwery proxy interfejsów API na podstawie dokumentów OpenAPI. Wystarczy kilka kliknięć, aby uzyskać serwer proxy interfejsu API ze ścieżkami, parametrami, przepływami warunkowymi i docelowymi punktami końcowymi generowanymi automatycznie. Następnie możesz dodać funkcje takie jak zabezpieczenia OAuth, ograniczanie liczby żądań i pamięć podręczna.

Serwer proxy interfejsu API możesz utworzyć na podstawie dokumentu OpenAPI zgodnie z opisem w tych sekcjach:

Podczas publikowania interfejsu API tworzysz migawkę dokumentu OpenAPI, aby wygenerować dokumentację API. Ten zrzut przedstawia konkretną wersję dokumentu z opisem w magazynie specyfikacji.