Forum Discussion

mschweers's avatar
mschweers
New Contributor
8 years ago

Getting the state of reviewers/participants via JSON API?

Greetings,

I'm trying to use your JSON API to retrieve the state of the reviewers on a review.  I don't seem to be able to find that information anywhere in the API reference.

 

I can retrieve the list of participants, and their roles, but I can't retrieve whether they've approved the review or not, yet.  I don't need to know the larger reviewPhase, but rather WHO of the people listed as participants has actually reviewed/approved the code yet.

 

Your in-app JavaDoc based documentation is exceedingly difficult to search through, and essentially unusable in places.  For instance, I can find no reasonable way to determine what clientGuid and clientBuild are for the other parameters for ReviewService.getReviewSummary.  So while that might be a useful call for what I'm doing (I don't know, the documentation doesn't say), I can't actually call it to learn because there's no documentation on how to obtain the non-review ID parameters.

 

I would appreciate any kind of pointers or information you can provide on how to determine the State (as displayed in the code review page) of each participant in a code review, via your JSON API.  It seems a somewhat fundamental capability of a code review system.

 

--  Morgan

5 Replies

Sort By
  • mschweers's avatar
    mschweers
    New Contributor
    8 years ago

    Greetings,

    Through almost no help of the docs, I discovered that I can elide the clientGuid and provide active: true and I get the review summary.

     

    Essentially:

     

    { command: "ReviewService.getReviewSummary", args: { clientBuild: 9200, reviewId: 900101, active: true } }

     

    will return the useful information.

     

    I only found this out because I sent: 

     

    { command: "ReviewService.getReviewSummary", args: { blah: "fake" } }

     

    and the error message listed the known entities, one of which was 'active'.  I guessed at the client build, just throwing a number in there that was related to Code Collaborator at one point.  I don't know if it's relevant, but it doesn't work without it.  The documentation is misleading, unfortunately.

     

    --  Morgan

     

    • AlexeyKryuchkov's avatar
      AlexeyKryuchkov
      Staff
      8 years ago

      Hi,

       

      Thanks for pointing the issue out. I'll ask our tech writers to look into it.

    • AlexeyKryuchkov's avatar
      AlexeyKryuchkov
      Staff
      8 years ago

      Hi again,

       

      Actually, it appears that all the mentioned properties are documented in the API help topic about the ReviewSummaryRequest interface. This interface is used as the argument type for the getReviewSummary method:

      • mschweers's avatar
        mschweers
        New Contributor
        8 years ago

        Greetings,

        I strongly disagree; there is absolutely no information about what is required for that call.  There is no information about what 'active' means, or why passing true and false returns the exact same data, but in a vaguely different order.  Or why passing ANYTHING that I've tried for clientGuid results in a NullPointerException.  Or what valid values for clientBuild are, or even WHY those values are required to get a ReviewSummary.

         

        Your documentation for the ReviewService.getReviewSummary call in your own post (which I read many times trying to understand this) implies that just reviewId, clientBuild and clientGuid are required, but clientGuid isn't, active is, and that's not called out.  Your JavaDoc is completely lacking for updateToken, active, and consolidationMethods, all of which are also apparently parameters, except that reviewId, clientBuild, and active are the only ones that are required.  I have no idea what those other parameters do, nor does anyone who isn't on your team and has access to the source code.

         

        It is impossible to implement to that documentation without flailing around, guessing at valid values, and tripping on the solution.  I'm sure it's easier for you folks, because you already know what they all mean, but your documentation makes no attempt to explain those parameters.  This is endemic in your docs.

         

        'Documentation' that consists exclusively of:

        public interface ClientBuildRequest

        A request to get client build number

        public interface ClientGuidRequest

        A request to get client guid number

        is half-hearted JavaDoc at best, and probably machine generated.  You need to explain what valid values are, and explain what it's used for, so the callers can have any marginal idea of how to build something for it.

         

        Properties are not documented unless an unrelated caller understands which to use, and why to use them.  Those properties, and that call (one of the most important in your set of calls) are not documented.

         

        I really do appreciate the API, and it's not the worst I've had to reverse-engineer, but the documentation DEFINITELY needs to be written, especially for that critical call.

         

        --  Morgan

         

  • brianmcnamara's avatar
    brianmcnamara
    Occasional Visitor
    7 years ago

    Thank you for posting this!! Holly crap I was about to throw my computer out the window trying to figure out why I kept getting a nullPointerException when calling this. I was setting reviewId, clientBuild and clientGuid (even though I have 0 idea what clientBuild and clientGuid even was!!!) Thank you mschweers for this post, you have saved me from contacting support as what I was beginning to think was a bug with their api.

     

    To Smart Bear, PLEASE for the love of all things good, fix your java doc. It is incorrect and should be fixed.  This post was almost a year ago and seems like it is still not fixed. I should also note that the error for specifying incorrect parameters should not be to throw a NPE.