Omówienie projektowania interfejsów API

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

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, musisz utworzyć jeden z tych dokumentów:

  • Dokument OpenAPI.
  • schemat GraphQL

Sekcje poniżej zawierają więcej informacji o dokumentach OpenAPI i GraphQL oraz o ich roli w cyklu życia interfejsu API. Porównanie 2 opcji projektowania interfejsów API znajdziesz w porównaniu metod REST i GraphQL z tego posta na blogu.

Jaka jest specyfikacja OpenAPI?


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

Dokument OpenAPI używa standardowego formatu do opisania interfejsu API typu REST. Dokument OpenAPI napisany w formacie JSON lub YAML jest zrozumiały dla komputera, ale też czytelny i zrozumiały dla użytkowników. 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 nie tylko. Poza tym dokument OpenAPI jest często używany do generowania dokumentacji API.

Oto fragment dokumentu OpenAPI opisującego prosty przykład interfejsu Apigee stworzona przez Apigee. Więcej informacji znajdziesz w specyfikacji OpenAPI na stronie 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. Warto zacząć od strony OpenAPI Initiative, gdzie znajdziesz omówienia, blogi i linki do specyfikacji OpenAPI. Szczegółowy opis elementów schematu i typów danych znajdziesz w specyfikacji.

Istnieje wiele przykładowych dokumentów OpenAPI w formacie JSON i YAML, które można pobrać ze strony repozytorium OpenAPI Specification,

Co to jest schemat GraphQL?

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

Zalety korzystania z GraphQL:

  • Pojedynczy punkt końcowy zapewnia dostęp do wszystkich pól danej operacji
  • Zaawansowany język zapytań, tzw. Schema Definition Language, zapewnia dostęp do dokładnie tych danych, których potrzebujesz, co zapobiega nadmiernemu lub zaniżonemu pobieraniu 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 zapytania), dostępne operacje zapisu (typ mutacji) 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ładne dane, których potrzebujesz jako ładunek JSON.

Zapytanie i wyniki GraphQL

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

Każdy dokument OpenAPI lub GraphQL służy jako źródło danych w całym cyklu życia interfejsu API. Ten sam dokument jest używany na każdym etapie cyklu życia interfejsu API, od programowania przez publikowanie po monitorowanie.

Zmodyfikowanie lub usunięcie dokumentu ma wpływ na:

  • Jeśli edytujesz dokument, musisz ręcznie edytować powiązane artefakty, w tym serwer proxy interfejsu API i wszystkie usługi API, które udostępniają jego zasoby, a następnie ponownie wygenerować dokumentację API, aby uwzględnić zmiany wprowadzone w dokumencie.
  • Jeśli usuniesz dokument, musisz ręcznie usunąć powiązane artefakty, w tym serwer proxy interfejsu API, i zmienić usługi API, aby usunąć powiązane zasoby. Następnie ponownie wygeneruj dokumentację API, aby uwzględnić usunięcie dokumentu i jego zasobów.

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

W Edge możesz tworzyć serwery proxy interfejsów API z dokumentów OpenAPI. Wystarczy kilka kliknięć, aby utworzyć 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 buforowanie.

Serwer proxy interfejsu API możesz utworzyć na podstawie dokumentu OpenAPI w sposób opisany w tych sekcjach:

Podczas publikowania interfejsu API generujesz zrzut dokumentu OpenAPI, aby wygenerować jego dokumentację referencyjną. Ten zrzut reprezentuje konkretną wersję dokumentu opisu w magazynie specyfikacji.