Issue #156: JSON-RPC methods are incorrectly documented

Reported by:	Brandon Jones
State:	new
Created on:	2015-09-10 23:57
Updated on:	2015-09-16 17:03

Description

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?

Attachments

Comments

Comment by Brandon Jones, on 2015-09-10 23:57

Comment by Brandon Jones, on 2015-09-10 23:58

Comment by Brandon Jones, on 2015-09-11 00:20

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).

Comment by Brandon Jones, on 2015-09-11 00:21

Comment by Mads Kiilerich, on 2015-09-11 00:22

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 ;-)

Comment by Brandon Jones, on 2015-09-11 00:27

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.

Comment by Brandon Jones, on 2015-09-16 17:03

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.

Kallithea issues archive