Block 10 hat sechs Zugriffspunkte gebaut (Kapitel 80-83) und in Kapitel 86 gegen Missbrauch abgesichert. Eine praktische Frage bleibt: Wie findet ein Partnersystem oder eine mobile App diese Endpunkte, ohne webapi.xml oder schema.graphqls im Quellcode zu lesen? Für keinen der beiden Fälle war in diesem Modul eine einzige Zeile zusätzlicher Dokumentations-Code nötig - REST und GraphQL bringen ihre Selbstbeschreibung bereits aus dem jeweiligen Framework mit.

Der automatisch generierte REST-Schema-Endpunkt

Magento_Webapi generiert aus jeder im System registrierten webapi.xml-Route ein Swagger-/OpenAPI-2.0-Dokument - ganz ohne projektspezifische Konfiguration. Die drei Service Contracts aus Block 10 tauchen darin automatisch unter denselben Servicenamen auf, die Kapitel 79 bereits am SOAP-WSDL-Beispiel gezeigt hat: RewardRepositoryInterface als mironsoftLoyaltyRewardRepositoryV1, PointsManagementInterface als mironsoftLoyaltyPointsManagementV1, RewardRedemptionManagementInterface als mironsoftLoyaltyRewardRedemptionManagementV1.

# Komplettes Schema aller registrierten Services:
curl -s https://mironsoft.test/rest/de/schema?services=all

# Nur die drei eigenen Loyalty-Services:
curl -s 'https://mironsoft.test/rest/de/schema?services=mironsoftLoyaltyRewardRepositoryV1,mironsoftLoyaltyPointsManagementV1,mironsoftLoyaltyRewardRedemptionManagementV1'

Magento Open Source liefert bewusst nur das rohe JSON-Dokument, keine eingebaute grafische Oberfläche dafür. Da es sich um ein Standard-Swagger-/OpenAPI-2.0-Format handelt, lässt es sich unverändert in Swagger UI, Postman oder Insomnia importieren - alle drei erkennen und rendern die Struktur ohne jede Anpassung von Hand.

GraphQL-Introspection: das Schema fragt sich selbst ab

GraphQL braucht keinen separaten Dokumentations-Endpunkt - Introspection ist Teil der Spezifikation selbst. Die Meta-Felder __schema und __type beantworten dieselbe Anfrage /graphql, die auch loyaltyPointsSummary oder redeemLoyaltyReward bedient, und liefern die vollständige Struktur aller in Kapitel 82/83 registrierten Typen zurück - LoyaltyPointsSummary, LoyaltyPointsLedgerEntry, LoyaltyReward, RedeemLoyaltyRewardInput, RedeemLoyaltyRewardOutput eingeschlossen.

query IntrospectRewardType {
  __type(name: "LoyaltyReward") {
    name
    fields {
      name
      description
      type { name kind }
    }
  }
}

Entdeckbarkeit und Absicherung sind zwei verschiedene Fragen

Derselbe Gedanke, der Kapitel 86 zu zwei getrennten Rate-Limiting-Ansätzen für redeemLoyaltyReward und loyaltyRewards geführt hat, gilt hier erneut: __schema zu blockieren würde nur verhindern, dass ein Client die Struktur der Felder entdeckt - jedes Feld bliebe trotzdem exakt so ausführbar und exakt so schutzbedürftig wie zuvor, GraphQlAuthorizationException (Kapitel 82/83) und der ThrottleRewardRedemptionPlugin (Kapitel 86) unverändert eingeschlossen. Dokumentation erleichtert die legitime Nutzung, sie ersetzt keine einzige der in diesem Block gebauten Schutzmaßnahmen.

Alle Dateien dieses Blocks im Überblick

app/code/Mironsoft/Loyalty/
├── Api/
│   ├── Data/
│   │   ├── RewardInterface.php                          (Kapitel 79)
│   │   ├── PointsSummaryInterface.php                   (Kapitel 80)
│   │   └── RewardRedemptionResultInterface.php          (Kapitel 81)
│   ├── RewardRepositoryInterface.php                    (Kapitel 79)
│   ├── PointsManagementInterface.php                    (Kapitel 80)
│   └── RewardRedemptionManagementInterface.php          (Kapitel 81)
├── Model/
│   ├── Data/
│   │   └── Reward.php                                   (Kapitel 79)
│   ├── RewardRepository.php                             (Kapitel 79)
│   ├── PointsManagement.php                             (Kapitel 80)
│   ├── RewardRedemptionManagement.php                   (Kapitel 81)
│   ├── RateLimiter/
│   │   └── RedemptionRateLimiter.php                    (Kapitel 86)
│   └── Resolver/
│       ├── PointsSummary.php                            (Kapitel 82)
│       ├── RewardCatalog.php                            (Kapitel 82)
│       ├── DataProvider/
│       │   └── RewardCatalog.php                        (Kapitel 82)
│       └── RedeemLoyaltyReward.php                      (Kapitel 83)
├── Plugin/
│   └── Api/
│       └── ThrottleRewardRedemptionPlugin.php           (Kapitel 86)
├── CustomerData/
│   └── PointsBalance.php                                (Kapitel 84)
├── etc/
│   ├── di.xml                                           (Kapitel 79/86, ergänzt)
│   ├── webapi.xml                                       (Kapitel 80/81)
│   ├── acl.xml                                          (Kapitel 80, ergänzt)
│   ├── schema.graphqls                                  (Kapitel 82/83)
│   ├── extension_attributes.xml                         (Kapitel 79)
│   └── frontend/
│       ├── sections.xml                                 (Kapitel 84)
│       └── di.xml                                       (Kapitel 84)
└── view/
    └── frontend/
        └── templates/
            └── customer-data/
                └── points-badge.phtml                   (Kapitel 84)

Checkliste: Block 10 zusammengefasst

1. Service Contract zuerst (Kapitel 79): Api\Data-Interface plus Repository, bevor überhaupt eine Transportschicht existiert.
2. REST registrieren (Kapitel 80/81): webapi.xml mit self/force für "mine"-Routen, eigene ACL-Ressourcen für alles darüber hinaus.
3. GraphQL registrieren (Kapitel 82/83): schema.graphqls plus dünner Resolver, der ausschließlich denselben Service Contract aufruft - keine zweite Implementierung derselben Logik.
4. Exceptions übersetzen (Kapitel 83): LocalizedException aus der Geschäftslogik wird im Resolver gezielt zu GraphQlInputException/GraphQlNoSuchEntityException, sonst verschwindet die Fehlermeldung hinter "Internal server error".
5. Das eigene Frontend bevorzugt Customer Section Data (Kapitel 84) statt eines eigenen GraphQL-Requests, wenn Daten ohnehin schon im selben Request-Zyklus verfügbar sind.
6. Stabilität dokumentieren (Kapitel 85): Extension Attributes statt neuer Interface-Methoden, @deprecated statt stillem Bedeutungswandel.
7. Missbrauch begrenzen (Kapitel 86): Rate-Limiting am gemeinsamen Service-Contract-Aufpunkt, nicht doppelt pro Transportschicht.
8. Entdeckbarkeit akzeptieren, nicht verwechseln mit Absicherung (Kapitel 87): REST-Schema und GraphQL-Introspection sind für jeden offen - alle vorherigen Schutzmaßnahmen bleiben trotzdem in Kraft.

Block 11 wendet sich als Nächstes der Konfiguration, Mehrsprachigkeit und Testabdeckung dieses Moduls zu - beginnend mit Kapitel 88, das eigene Konfigurationstypen jenseits des in Kapitel 7 gebauten System/Config/Setting einführt.