Diaspora API Dev Progress Report 14

Yesterday was the first day in several I could commit to real time towards D* again.  After getting back up to speed and making the status post I went on into the API development again.  I was able to make some good progress on some brand new endpoints.  The first one I worked, which is the first that needed from scratch coding of the main code, was the Tag Followings controller.  The day before I had struggled getting Rails to make the POST for creating tags work against the spec.  However after talking it over and thinking about it it was the spec that needed changing.  In another software framework I could just make it work but relying on the auto-wiring in Rails brought the design flaw nature to light.  With a simple change starting yesterday real development of the Tag Followings endpoint started.

The methodology I’m using when developing the new controllers is as follows.  First, I want to get the basic infrastructure in place and the tests.  That means that the first phase is to write the skeleton of the controller code, the skeleton of the RSpec tests, and to wire the two together.  I make sure that the routes behave the way I think they should according to the API Spec without worrying about returns etc.  The skeleton of the controller should implement all routes.  The skeleton of the unit tests should be testing for happy path and reasonable error conditions.  So that’s stuff like: the user passes the wrong ID for a post that they are trying to comment on, or an empty new tag to follow, etc.  I then go over to the external test application and code up the corresponding code in there as well.  With everything running I make sure that the endpoint is reachable from the outside (which it should be), but don’t worry about returns, processing etc.  If it’s possible to setup fake returns easily I do that otherwise I just ensure the proper methods are called.  After all of that is coded and committed then it is off to filling in the controller method by method.  For each one coded up I complete the unit tests and the external test harness interactions as well.  Once that’s all done then I move on to the next one.  In some cases, like Tag Followings, there needs to be refactoring elsewhere which has implications on the above flow.  I usually do those pieces before coding the controller.  It is at the design time that whether I should be using common code with another controller which may not exist as a Service component becomes apparent.  If I need to make any changes over  in other code I check that there are unit tests which properly cover the changes I am going to make, at least as best as I can tell, write those and then make the changes.  This should minimize the possibility of disruption.

When interacting with Frank R. on the merge requests one of the pieces of feedback I got was that with everything compressed down to one commit it was hard to tell why I did certain things.  As I code all of that is there but I’ve been rebasing everything down to one commit per endpoint so that when it comes time to merge the API branch into the main develop the log will look something like: Post API endpoint complete, Comments API endpoint complete, etc.  To get around this I’m trying a new flow.  When I think something is ready to be merged i’m doing a Work in Progress (WIP) Pull Request (PR).  That PR has the raw commit history and the name “WIP” in the leader of the label.  After a review and a thumbs up I’m going to rebase it down to one commit and then submit the final one for integration.  By the time WIP is done the code is feature complete however and should be ready to be merged.  I’m therefore counting WIP PR’s as the threshold for saying something is feature complete.

With all that said the three new endpoints that were feature complete as of yesterday are: Tag Followings, Aspects, and Reshares.