Api-blueprint: Unterstützung der URI-Überladung für JSON-RPC

Umzug zu apiary.io.

@rodriguise Wo finde ich Informationen zu diesem Problem? Ich habe den gleichen Gedanken, es wäre eine nette Funktion, RPC-ähnliche APIs zu unterstützen.

@rodriguise Ich interessiere mich auch sehr für diese Funktionalität.

@adammbalogh @SvyatoslavVasiliev Können Sie Ihren Anwendungsfall etwas genauer beschreiben?

@pksunkara sicher.
Ich habe eine API, die gemäß der JSON-RPC 2.0-Spezifikation entwickelt wurde , zum Beispiel:

POST http://somehost.com/rpc_api

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "entity.get",
  "params": {
    "filter": {
      "filters": [
        {
          "field": "name",
          "operator": "eq",
          "value": "Bob"
        },
        {
          "field": "age",
          "operator": "eq",
          "value": 25
        }
      ],
      "condition": "and"
    }
  }
}

Eine solche API hat nur eine URL für die Methodengruppe, in der die Namen der Methoden im Hauptteil enthalten sind, im Parameter "method".
Die aktuelle Blueprint-Realisierung erlaubt es aufgrund der pfadorientierten Sprachstruktur nicht, eine solche API zu beschreiben.

Hallo @pksunkara , hast du Neuigkeiten dazu?
Ich habe versucht, anstelle des Bienenhauses andere Rendering-Tools (z. B. Aglio) zu verwenden, und sie stellten die Dokumentation im Gegensatz zum Bienenhaus korrekt dar. Diese Tools unterstützen jedoch nicht das Rendern einiger Funktionen wie Attribute als separater Abschnitt.
Es wäre sehr nett, wenn Sie mir helfen, mein Problem zu lösen.

Hey @SvyatoslavVasiliev also, wenn ich das richtig gelesen habe, fällt eine Unterstützung für JSON RPC unter https://github.com/apiaryio/api-blueprint/issues/289, obwohl das Protokoll technisch immer noch HTTP ist.

Die Entkopplung der Ressourcen- und Aktionsdefinitionen von URIs und HTTP-Methoden sollte auch in diesem Fall helfen.

Macht das Sinn? Weitere Informationen finden Sie unter Nr. 289

Hallo @zdne ,
Ich habe versucht, #289 zu verstehen, aber ich bin nicht in der Lage, es vollständig zu verstehen.
Meine API verwendet HTTP mit JSON-Body als Transport, aber sie hat nur eine URL und verwendet nur HTTP POST. Alle Informationen über Ressource und Methode, die in "method" param enthalten sind, werden in den Body übertragen.
Rufen Sie beispielsweise die Entität ab:
{ "jsonrpc": "2.0", "id": 1, "method": "entity.get", "params": { "filter": { "filters": [ { "field": "name", "operator": "eq", "value": "Bob" }, { "field": "age", "operator": "eq", "value": 25 } ], "condition": "and" } } }

Entität löschen:
{ "jsonrpc": "2.0", "id": 1, "method": "entity.delete", "params": { "id": "123" } }

Beide Methoden heißen HTTP POST http://myservice.com/rpcapi

Bisher habe ich keine moderne und funktionale Möglichkeit gefunden, eine JSON-RPC-API (mit der ich auch Tests generieren kann) zu dokumentieren. Meine Hoffnung war API Blueprint, aber es scheint, dass es nicht wirklich unterstützt wird. Kennt jemand die zukünftigen Pläne von API Blueprint oder hat einen Vorschlag für eine andere Struktur / ein anderes Tool, das dies unterstützt?

@Dynom Ich kann ein paar Ratschläge geben.
Sie können Aglio render for api blueprint ausprobieren, es rendert den Abschnitt mit den Attributen nicht, zeigt jedoch die Dokumentstruktur korrekt an.
Ein weiteres Tool ist API Doc , ich teste es im Moment und es scheint geeignet zu sein.

Danke @SvyatoslavVasiliev Ich möchte keine Inline-Dokumentationslösungen verwenden und API Doc wirbt damit für RESTful-Dienste, daher bin ich mir nicht sicher, ob wir auf lange Sicht viel davon erwarten können.