Omówienie projektowania interfejsów API

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

W fazie projektowania określasz wymagania dotyczące interfejsu API. Jako projektant interfejsu 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 dotyczące interfejsu API, utwórz jeden z tych dokumentów:

  • dokument OpenAPI,
  • schemat GraphQL,

W kolejnych sekcjach znajdziesz więcej informacji o dokumentach OpenAPI i GraphQL oraz o ich roli w cyklu życia interfejsu API. Porównanie tych 2 opcji projektowania interfejsu API znajdziesz w tym poście na blogu.

Czym jest specyfikacja OpenAPI?


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

Dokument OpenAPI używa standardowego formatu do opisywania interfejsu API typu REST. Dokument OpenAPI jest napisany w formacie JSON lub YAML i jest czytelny dla komputera, a także łatwy do odczytania i zrozumienia dla człowieka. Specyfikacja OpenAPI umożliwia formalny opis elementów interfejsu API, takich jak ścieżka podstawowa, ścieżki i czasowniki, nagłówki, parametry zapytania, typy treści, modele odpowiedzi i inne. Dokument OpenAPI jest też często używany do generowania dokumentacji API.

Oto fragment dokumentu OpenAPI, który opisuje 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 o specyfikacjach OpenAPI. Dobrym miejscem na rozpoczęcie jest strona OpenAPI Initiative, na której znajdziesz omówienia, blogi i linki do specyfikacji OpenAPI. Szczegółowe opisy elementów schematu i typów danych znajdziesz w specyfikacji.

W repozytorium specyfikacji OpenAPI możesz pobrać wiele przykładowych dokumentów OpenAPI w formatach JSON i YAML.

Czym jest schemat GraphQL?

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

Zalety korzystania z GraphQL:

  • Jeden punkt końcowy zapewnia dostęp do wszystkich pól w przypadku danej operacji.
  • Zaawansowany język zapytań o nazwie Schema Definition Language umożliwia dostęp do dokładnie tych danych, których potrzebujesz, zapobiegając pobieraniu zbyt dużej lub zbyt małej ilości danych.
  • Przetwarzanie zapytań odbywa się równolegle

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

Poniżej znajdziesz przykład schematu GraphQL, który definiuje punkt wejścia danych (typ Query), dostępne operacje zapisu (typ Mutation) 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 wysłać zapytanie do schematu GraphQL, aby zwrócić dokładne dane, których potrzebujesz, w postaci ładunku JSON.

Zapytanie GraphQL i wyniki

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

Każdy dokument OpenAPI lub GraphQL stanowi źródło informacji w całym cyklu życia interfejsu API. Ten sam dokument jest używany na każdym etapie cyklu życia interfejsu API – od tworzenia przez publikowanie po monitorowanie.

Edytowanie lub usuwanie dokumentu ma wpływ na dalsze działania:

  • Jeśli edytujesz dokument, musisz ręcznie zmodyfikować powiązane artefakty, w tym proxy interfejsu API i wszystkie usługi API, które udostępniają jego zasoby, oraz ponownie wygenerować dokumentację API, aby odzwierciedlić zmiany wprowadzone w dokumencie.
  • Jeśli usuniesz dokument, musisz ręcznie usunąć powiązane artefakty, w tym proxy interfejsu API, i zmodyfikować wszystkie produkty interfejsu API, aby usunąć powiązane zasoby, a następnie ponownie wygenerować dokumentację 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ć proxy interfejsu API na podstawie dokumentów OpenAPI. Wystarczy kilka kliknięć, aby utworzyć serwer proxy interfejsu API z automatycznie wygenerowanymi ścieżkami, parametrami, przepływami warunkowymi i docelowymi punktami końcowymi. Następnie możesz dodać funkcje takie jak zabezpieczenia OAuth, ograniczenia liczby żądań i pamięć podręczna.

Możesz utworzyć proxy interfejsu API na podstawie dokumentu OpenAPI, jak opisano w sekcjach poniżej:

Gdy opublikujesz interfejs API, utworzysz zrzut dokumentu OpenAPI, aby wygenerować dokumentację API. Ten migawka reprezentuje konkretną wersję dokumentu opisu w sklepie ze specyfikacjami.