JSON-RPC methods are incorrectly documented

Issue #156 new
Brandon Jones created an issue

I have a .NET wrapper around the JSON-RPC API for Kallithea. While performing some testing, I noticed that what is being returned for the get_repos command is formatted differently than is documented.

Here is what is documented...

 [
          {
            "repo_id" :          "<repo_id>",
            "repo_name" :        "<reponame>",
            "repo_type" :        "<repo_type>",
            "clone_uri" :        "<clone_uri>",
            "private": :         "<bool>",
            "created_on" :       "<datetimecreated>",
            "description" :      "<description>",
            "landing_rev":       "<landing_rev>",
            "owner":             "<repo_owner>",
            "fork_of":           "<name_of_fork_parent>",
            "enable_downloads":  "<bool>",
            "enable_locking":    "<bool>",
            "enable_statistics": "<bool>",
          },
]

Here is what is being returned...

[
  {
            "repo_id" :          "<repo_id>",
            "repo_type" :        "<repo_type>",
            "description" :      "<description>",
            "private" :          "<bool>",
            "last_changeset": {
              "raw_id": "0000000000000000000000000000000000000000",
              "short_id": "000000000000",
              "author": "",
              "date": "1969-12-31T19:00:00",
              "message": "",
              "revision": -1
             },
            "created_on" :       "<datetimecreated>",
            "fork_of":           "<name_of_fork_parent>",
            "enable_locking":    "<bool>",
            "owner":             "<repo_owner>",
            "locked_date":     null,
            "landing_rev": [
              "rev",
              "tip"
            ],
            "enable_downloads":  "<bool>",
            "enable_statistics": "<bool>",
            "locked_by": null,
            "clone_uri" :        "<clone_uri>",
  },
]

last_changeset, locked_date, landing_rev, and locked_by are all new or changed outputs.

I have not had errors with any other methods, but it is possible they also have additional data in them that is not documented.

Am I missing something here?

Comments (8)

  1. Brandon Jones reporter

    I'm also finding that other commands, such as get_gist, are actually supported. I have forked the repository and will update the documentation with a full list of supported commands (and rename this issue to represent that).

  2. Mads Kiilerich

    You are probably right ... and there are probably many other bugs. I have fixed some but do not feel like I have found them all. The API documentation should really be tested and/or somehow be generated from the code automatically.

    Patches fixing the documentation would be appreciated. Automation even more ;-)

  3. Brandon Jones reporter

    I am updating my old RhodeCode .NET API Wrapper to work with Kallithea so I am doing full regression testing on it (which is why this came about). I will discover what other API methods are implemented and update the documentation manually, for the sake of brevity.

    Though I agree, automatically generating API documentation is definitely a plus. :+1: Perhaps I will adapt my unit-testing of the API wrapper to generate documentation down the road.

  4. Brandon Jones reporter

    Using Sphinx and Autodoc it is possible to automatically generate the API documentation, though there are limitations on the format. Still playing around with it. Might just have it created manually in the conf.py for Sphinx. Will fork and submit pull request when finished.

  5. Log in to comment