Api-blueprint: Prise en charge de la surcharge d'URI pour JSON-RPC

Passage à apiary.io.

@rodriguise Où puis-je trouver des informations sur ce problème ? J'ai la même pensée, ce serait une fonctionnalité intéressante pour prendre en charge les API de type RPC.

@rodriguise Je suis également très intéressé par cette fonctionnalité, pourriez-vous dire où je peux en savoir plus sur ce problème ?

@adammbalogh @SvyatoslavVasiliev Pouvez-vous décrire un peu plus votre cas d'utilisation ?

@pksunkara bien sûr.
J'ai une API conçue selon la spécification JSON-RPC 2.0 , par exemple :

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

Une telle API n'a qu'une seule URL pour le groupe de méthodes, où les noms des méthodes sont contenus dans le corps, dans le paramètre "method".
La réalisation actuelle du Blueprint ne permet pas de décrire une telle API, en raison de la structure du langage centrée sur le chemin.

Salut @pksunkara , avez-vous des nouvelles à ce sujet ?
J'ai essayé d'utiliser d'autres outils de rendu (aglio par exemple) à la place du rucher, et ils représentaient correctement la documentation, contrairement au rucher. Mais ces outils ne prennent pas en charge le rendu de certaines fonctionnalités telles que les attributs en tant que section distincte.
Ce serait très gentil si vous m'aidez à résoudre mon problème.

Hé @SvyatoslavVasiliev, donc si je lis ceci correctement, la prise en charge de JSON RPC relève de https://github.com/apiaryio/api-blueprint/issues/289, bien que techniquement, le protocole soit toujours HTTP.

Le découplage des ressources et des définitions d'action des URI et des méthodes HTTP devrait également aider ce cas.

Cela a-t-il du sens ? S'il vous plaît voir #289 pour plus de détails

Salut @zdne ,
J'ai essayé de comprendre #289, mais je n'arrive pas à le comprendre complètement.
Mon API utilise HTTP avec le corps JSON comme transport, mais elle n'a qu'une seule URL et utilise uniquement HTTP POST. Toutes les informations sur la ressource et la méthode contenues dans le paramètre "method" dans le corps.
Par exemple, obtenez l'entité :
{ "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" } } }

supprimer l'entité :
{ "jsonrpc": "2.0", "id": 1, "method": "entity.delete", "params": { "id": "123" } }

Les deux méthodes appelées HTTP POST http://myservice.com/rpcapi

Jusqu'à présent, je n'ai pas trouvé de moyen moderne et fonctionnel de documenter une API JSON-RPC (que je peux également utiliser pour générer des tests). Mon espoir était API Blueprint mais il semble qu'il ne soit pas vraiment pris en charge. Est-ce que quelqu'un connaît les plans futurs de l'API Blueprint à ce sujet ou a-t-il une suggestion pour une structure/un outil différent qui prend en charge cela ?

@Dynom Je peux donner quelques conseils.
Vous pouvez essayer le rendu Aglio pour le plan api, il ne rend pas la section des attributs, mais affiche correctement la structure du document.
Un autre outil est API Doc , je le teste actuellement et il me semble approprié.

Merci @SvyatoslavVasiliev Je ne veux pas utiliser de solutions de documentation en ligne et API Doc annonce que c'est pour les services RESTful, donc je ne sais pas si nous pouvons en attendre grand-chose à long terme.