API-Design

Sie sehen sich die Dokumentation zu Apigee Edge an.
Sehen Sie sich die Apigee X-Dokumentation an. info

In der Designphase definieren Sie die Anforderungen an Ihre API. Als API-Designer planen Sie Dienste, die Sie Nutzern anbieten möchten, und entwerfen APIs, um auf diese Dienste zuzugreifen. Zum Erfassen Ihrer API-Anforderungen erstellen Sie eines der folgenden Dokumente:

  • Ein OpenAPI-Dokument
  • Ein GraphQL-Schema

In folgenden Abschnitten finden Sie weitere Informationen zu OpenAPI- und GraphQL-Dokumenten und zu der Rolle, die sie im Lebenszyklus Ihrer API spielen. Einen Vergleich der beiden API-Designoptionen finden Sie unter REST und GraphQL in diesem Blogpost.

Was ist die OpenAPI-Spezifikation?


„Die Open API-Initiative (OAI) konzentriert sich auf das Erstellen, Entwickeln und Bewerben eines neutralen API-Beschreibungsformats basierend auf der Swagger-Spezifikation.” Weitere Informationen zur Open API-Initiative finden Sie unter https://openapis.org.

Ein OpenAPI-Dokument verwendet ein Standardformat zur Beschreibung einer RESTful API. Ein OpenAPI-Dokument, im JSON- oder YAML-Format geschrieben, ist maschinenlesbar, aber auch für menschliche Nutzer leicht lesbar. Die OpenAPI-Spezifikation ermöglicht eine formelle Beschreibung von Elementen einer API, darunter Basispfad, Pfade und Verben, Header, Abfrageparameter, Inhaltstypen, Antwortmodelle und mehr. Außerdem wird ein OpenAPI-Dokument häufig zum Generieren einer API-Dokumentation verwendet.

Hier ist ein Fragment einer OpenAPI-Spezifikation, das Apigees einfaches "Hello World"-Sample beschreibt. Weitere Informationen finden Sie in der OpenAPI-Spezifikation auf 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
...

Es gibt viele hervorragende Informationsquellen zu OpenAPI-Spezifikationen. Ein guter Ausgangspunkt ist die Website der Open API Initiative mit Übersichten, Blogs und Links zu der OpenAPI-Spezifikation. Detaillierte Beschreibungen der Schemaelemente und Datentypen finden Sie in der Spezifikation.

Es gibt eine Reihe an JSON- und YAML-Beispiel-OpenAPI-dokumenten, die Sie aus dem OpenAPI-Spezifikations-Repository herunterladen können.

Was ist ein GraphQL-Schema?

Ein GraphQL-Schema beschreibt die Daten, die in Ihrer API für einen Client zum Abfragen verfügbar sind.

GraphQL bietet folgende Vorteile:

  • Ein einzelner Endpunkt bietet Zugriff auf alle Felder für einen bestimmten Vorgang.
  • Mit der leistungsstarken Abfragesprache, der Schemadefinitionsprache, können Sie genau auf die Daten zugreifen, die Sie benötigen, und so einen Datenabruf im Übermaß oder zu wenig Datenabruf verhindern.
  • Die Verarbeitung von Abfragen erfolgt parallel.

Weitere Informationen zu GraphQL finden Sie unter graphql.org.

Im Folgenden finden Sie ein Beispiel für ein GraphQL-Schema, das den Dateneinstiegspunkt (Abfragetyp), die verfügbaren Schreibvorgänge (Mutationstyp) und Datentypen definiert.

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

Sie können das GraphQL-Schema abfragen, um die benötigten Daten als JSON-Nutzlast zu erhalten.

GraphQL-Abfrage und -Ergebnisse

Was geschieht, wenn ich eine Dokument ändere?

Jedes OpenAPI- oder GraphQL-Dokument dient während des gesamten API-Lebenszyklus als "Source of Truth”. Die gleiche Dokument wird in jeder Phase des API-Lebenszyklus verwendet, von der Entwicklung über die Veröffentlichung bis hin zum Monitoring.

Wenn Sie ein Dokument bearbeiten oder löschen, hat dies Auswirkungen:

  • Wenn Sie eine Dokument bearbeiten, müssen Sie die zugehörigen Artefakte manuell bearbeiten, einschließlich des API-Proxys und aller API-Produkte, die dessen Ressourcen bereitstellen. Außerdem müssen Sie die API-Referenzdokumentation neu generieren und dabei die in der Dokument implementierten Änderungen vermerken.
  • Wenn Sie eine Dokument löschen, müssen Sie die zugehörigen Artefakte, einschließlich des API-Proxys, manuell löschen. Weiter sind alle API-Produkte zu bearbeiten, um die zugehörigen Ressourcen zu löschen. Anschließend muss die API-Referenzdokumentation neu generiert werden, wobei das Löschen des Dokuments und ihrer Ressourcen zu vermerken ist.

Was passiert, wenn ich API-Proxy aus OpenAPI-Dokument erstelle?

In Edge können Sie Ihre API-Proxys aus Ihren OpenAPI-Dokumenten erstellen. Mit nur wenigen Klicks erhalten Sie einen API-Proxy mit automatisch generierten Pfaden, Parametern, bedingten Abläufen und Zielendpunkten. Anschließend können Sie Funktionen wie OAuth-Sicherheit, Ratenbegrenzung und Caching hinzufügen.

Sie können einen API-Proxy aus einem OpenAPI-Dokument erstellen, wie in den folgenden Abschnitten beschrieben:

Wenn Sie Ihre API veröffentlichen, erstellen Sie einen Snapshot des OpenAPI-Dokuments, um eine API-Referenzdokumentation zu generieren. Dieser Snapshot stellt eine bestimmte Version des Beschreibungsdokuments im Spezifikationsspeicher dar.