API-Erweiterungen

Der Abschnitt resources enthält eine Gruppe von Ressourcendefinitionen, wobei jede Definition mindestens Folgendes enthält:

• Ein Name für die Ressource
• Zeiger auf ein Schema des Typs object , das die Ressource modelliert
• Eine Sammlung von Methoden, die für die Ressource ausgeführt werden

Normalerweise gibt eine Ressourcendefinition auch ein Feld innerhalb des Schemas an, in dem eine eindeutige ID für Instanzen dieses Typs gespeichert wird.

Betrachten Sie beispielsweise den folgenden Auszug aus einer API-Erweiterung:

resources:
  Book:
    schemas:
      primary:
        json_ptr: '#/definitions/Book'
    properties:
      id_name: '$.book_id'
    operations:
      create:
        - json_ptr: '#/paths/~1books/post'
      retrieve:
        - json_ptr: '#/paths/~1books~1{book_id}/get'
        - json_ptr: '#/paths/~1books/get'
      update:
        - json_ptr: '#/paths/~1books~1{book_id}/put'
      delete:
        - json_ptr: '#/paths/~1books~1{book_id}/delete'

Der Abschnitt resources enthält eine einzelne Ressourcendefinition mit den folgenden Eigenschaften:

• Sie definiert eine Ressource mit dem Namen Book
• Ein Buch wird durch ein Schema mit demselben Namen modelliert, das sich im Dokument OpenAPI unter definitions befindet.
• Jedes Buch hat eine Eigenschaft book_id , die seine eindeutige ID enthält
• Im Dokument OpenAPI unter paths sind Operationen definiert, die Bücher erstellen, abrufen, aktualisieren und löschen.

Die Übereinstimmung zwischen dem Ressourcennamen und dem Schemanamen ist allgemein, aber nicht erforderlich: Ein Ressourcenname kann beliebig sein, solange er innerhalb der API eindeutig ist.

Das eindeutige ID-Feld für ein Buch wird durch eine vereinfachte Form des JSON-Pfadausdrucks identifiziert, der eine Eigenschaft (book_id) innerhalb des primären Schemas lokalisiert.

Operationen (oder Methoden) für eine Ressource werden nach Kategorie gruppiert:

• Erstellen
• Abrufen
• Aktualisieren!
• Löschen

Es können mehrere Operationen in jeder vorhanden sein. In diesem Beispiel gibt es zwei Operationen, die Bücher abrufen: eine, die ein einzelnes Buch nach ID zurückgibt, und eine andere, die eine Liste von Büchern zurückgibt, und dies ist allgemein. Eine andere Definition kann patch sowie (oder anstelle) put unter updateenthalten.

JSON-Zeigerausdrücke in einer Ressourcendefinition verweisen alle implizit auf das zugehörige OpenAPI -Dokument, sodass das Präfix # eine relative Position innerhalb des Dokuments einführt. Die JSON-Zeigersyntax verwendet die Zeichenfolge ~1 , um für einen Schrägstrich (/) zu stehen, um Verwechslungen mit demselben Zeichen zu vermeiden, das als Trennzeichen verwendet wird, sodass die im OpenAPI -Dokument definierte Operation durch den Begriff definiert wird:

paths:
  /books/{book_id}:
    get:

wird hier durch den JSON-Zeiger angegeben:

#/paths/~1books~1{book_id}/get

  Order:
    schemas:
      primary:
        json_ptr: '#/definitions/Order'
    properties:
      id_name: '$.order_id'
    dependencies:
      - name: Book
        required: true
        references:
          - name: $.book_id
            in: body
        dependee_deletion: disabled
      - name: Customer
        required: true
        references:
          - name: customer_id
            in: path
        dependee_deletion: mutual
    operations:
      create:
        - json_ptr: '#/paths/~1customers~1{customer_id}~1orders~1{order_id}/post'
      # rest omitted for brevity

/customer/{customer_id}/orders/{order_id}

ServiceAvailability:
  schemas:
    primary:
      json_ptr: '#/definitions/ServiceAvailability'
    operations:
      pure:
        - json_ptr: '#/paths/~1service~1status/get'

Der Abschnitt properties weist Schemaeigenschaften, die in Operationsnutzdaten auftreten, semantische Kategorien zu, um den Wertebereich zu beschränken, der in generierte Anforderungshauptteile interpoliert wird.

Zum Beispiel:

properties:
  - json_ptr: '#/definitions/CardPayment'
    items:
      - name: card_number
        semantic: credit_card_number
      - name: expiry_date
        semantic: expiry
      - name: security_code
        semantic: cvv

Der JSON-Zeigerausdruck lokalisiert ein Schema mit dem Namen CardPayment im API-Dokument unter definitions. Das Schema muss den Typ object mit mindestens den Eigenschaften card_number, expiry_date und security_code haben, die hier angegeben sind, um eine bestimmte Semantik zu haben, die die automatische Generierung geeigneter Werte leitet, wenn ein CardPayment in Anforderungsnutzdaten auftritt.

Semantische Kategorien müssen aus dem folgenden Satz gezogen werden:

address                 cvv                     latitude                state_code
age                     date                    longitude               street
area_code               domain                  minutes                 temperature
birthday                email                   month                   time
certificate             expiry                  name                    timestamp
charset                 first_name              number                  token
cidr                    gender                  paragraph               twitter
city                    geo_location            percentage              url
color                   hours                   phone                   user_agent
content_encoding        humidity                phone_number            username
content_type            iban                    prefix                  uuid
coordinates             id                      pressure                version
country                 identity_provider       price                   year
country_code            ip_address              revision                zip_code
credit_card_number      language                sentence
currency                language_code           social_security_number
currency_code           last_name               state

Collection verweist auf ein Schema, das eine Reihe von Ressourcen beschreibt. Es wird in der Regel verwendet, um eine Liste von Ressourcen abzurufen.