Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
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.
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?
Sie können Ihre API-Proxys aus Ihren OpenAPI-Dokumente 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 mit dem Create Proxy Wizard einen API-Proxy aus einer OpenAPI-Dokument erstellen, wie unter Open API-Spezifikationen zum Generieren von Proxys verwenden beschrieben. Um das in der Praxis zu erleben, können Sie das Tutorial API-Proxy aus einer OpenAPI-Spezifikation erstellen durchgehen.
Wenn Sie Ihre API veröffentlichen, erstellen Sie einen Snapshot des OpenAPI-Dokuments, um eine API-Referenzdokumentation zu generieren. Dieser Snapshot repräsentiert eine bestimmte Überarbeitung des Beschreibungsdokuments.