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.
After a week of distractions I finally have a new update on the progress. We’ve successfully merged all the work done to date into the one main API branch and are now working on new features moving forward. The first feature we have completed with full tests and test harness interaction is the ability to manage and work with the user’s followed tags. So we have the full post lifecycle from before, and now tags done but not merged into the main branch yet.
The merging of the various side branches into the main branch is coming along. Because this isn’t being done as a primary job there is a bit of an expected delay between the pull request (PR) being generated and the branch being merged in. This is giving me the opportunity to work on other features on Diaspora though. The process is going along much faster than I expected it to, which is good. At this point we have merged the Likes, Comments, and Post Endpoints together. The PR on the Post Endpoint is now queued up however all of those changes exist in one branch. What that means is that I was able to perform a full Post life cycle test using the test harness. This means that we have an external application talking through the API and doing the following for a user:
- Creating a post
- Querying for the post and printing out it’s data
- Adding a comment to the post
- Liking to the post
- Printing out the comments and who liked the post
- Deleting their comment on a post
- Unliking a post
- Deleting a post
This is a very important step. Follow additional progress on the API Progress Google Sheet.
It’s been a few days since I’ve been able to put some real time into Diaspora development but I’m back today. Being back home from travel too means I can finally get past the blockers on the other branches. I’ve actually gotten all of the branches I had been developing on to feature complete status, with full tests, and the test harness fully coded against it. That means that through the API one can complete the entire Post, Comment, Like, etc. lifecycle for posts with all data types (regular, Photos, Polls, location, etc). Conversations are also feature complete with full test harness as well. Streams are also complete, however I haven’t tested with sufficient post volumes to test paging behavior. Now it’s going to be the trick of getting past the tech debt of getting them merged together into the API branch. Hopefully that’ll come in the next day or two. I’m going to spend some time doing other Diaspora stuff besides that as I work through those pieces as well. As always follow the progress on the API Progress Google Sheet. After the merge I’ll be moving on to the Tags Endpoint, the first endpoint that is a full from scratch development for me.
- Fully feature complete endpoints with full external test harness interaction completed are: Comments, Conversations, Likes, Posts, and Streams (except for paging behavior).
- Ready for merging of the side branches into the main API branch
Even though it was another short day on the road it was a productive day. The Conversations Endpoint’s Messages method got completed shortly after I typed up the previous day’s status message this morning. I then jumped onto the Streams API.
Continue reading Diaspora API Dev Progress Report 10
I’m still on the road so my contributions aren’t as great as I’d like them to be but I did manage to make some progress on the API development. At this point Conversations Endpoint minus the message listing of a conversation itself (next up). The test harness is coded up against the Conversations such that it can create, read, and hide/ignore them. As I finish up the Conversations Endpoint work and wrap up the Posts Endpoint work when I get back home I will soon be leaving the world of reviewing the existing implementation done by Frank while augmenting the tests, writing test harnesses, and making changes to get all of the tests to pass. I will then be entering the world of from scratch development on the rest of the API.
While I’m on the road I’ve been hoping to get some more work in on the API. Yesterday was a bust, and I knew it would be. Today looked like it was going to be a bust but I actually was able to get some time in tonight due to some plans that were cancelled last minute. As I sat down to start working I realized that I hadn’t been quite as prepared to develop on the road as possible. Before leaving I made sure my development laptop Ruby VM was fully configured, could compile the main code and the Kotlin test harness. I was all good to go! Except, I forgot to push my work up to the GitHub and Gitlab. Oops. Well, that derailed continuing work on the Posts API Endpoint, but with plenty more endpoints to go I started up on the Conversations endpoint, the next most filled in one to start from.
I did make a good amount of progress of fleshing out the unit tests and making some code changes to make the requests and returns on the Create method to correspond to the specification. It was at that point I realized I didn’t quite test my setup even further. I didn’t have a registered application in my OpenID setup on this dev instance. I also didn’t have the configurations I used when I set it up on my main development machine either. After some fumbling around I did manage to get it registered so I could then start testing the external test harness against the endpoint. After some final code tweaks I got that up and running and now have the test harness generating new conversations between two users! On to the rest of the conversations API tomorrow!
I’m still making good albeit slow progress on the Posts Endpoint. While the Posts Endpoint doesn’t have a lot of methods the complexity of the send and the return data is far greater than the other endpoints I’ve done so far. Posts have more than just text. They can have polls, geolocation data, mentions, aspects management, and photos. Yet posts are the core of the whole system. They are the digital elements we interact with the most. So progress on this endpoint is crucial. I’m pleased to say that at this point I’ve made enough progress with the unit tests and the test harness that from an external application I have been able to do have an external program do the full lifecycle of posting: Create a post, read a post, comment on a post, and like a post. I’m pretty stoked about that! While I have the full complement of all post data available on the GET method tested, I still have to create the test harness test methods around pushing posts with ancillary data (location, polls, mentions, photos), and need to write the unit tests for photos as well. The Photos endpoint for uploading photos during a real post creation process is a whole other matter though, but we’ll get to it soon enough!
Today I didn’t get as much progress as I had hoped on the API but still important work was done. Yesterday I discovered that something was probably off in the way that the repository rebasing was done when I did it about a week ago. Today I confirmed it. Working with Benjamin Neff (SuperTux) I was able to figure out a path forward for correcting the problem. While the git commands are pretty straight forward, me being comfortable that I’ve done it correctly is another matter so I did the process three times in a row. Each time I looked at the corresponding git log afterward and did a three way diff of the API branch head before the new rebase, the API branch head after the rebase, and the main Diaspora develop branch. I may end up doing it a fourth time (or reconfirm this last time anyway) before doing a final push after talking with Frank about it.
After getting past that I spent the other half of the time making actual progress on development. Thanks to Dennis Schubert’s (DensChub) efforts we were able to make some progress on some API questions I had. After that I made changes to the respective implementations to make it consistent. Then I went back to the Posts Endpoint testing. I completed the full GET path happy path testing for simple and fully filled in posts (text, photos, polls, mentions, and location). I now have to add in failure path testing on the GET, and the corresponding test harness methods to complete that and move on to posting and deleting Posts.
Another day another progress report on the state of the Diaspora API development. I had hoped by now that I’d be picking up a little more speed but I always underestimate how minute working on high coverage unit tests are. If I was doing a whack it together MVP startup-mode app I would always put automated tests around it for my own sanity but since things are going to change, or maybe even get thrown away entirely, in relatively short order there’s no need to go gnat’s ass down to the details. That’s not the case with the API. Yes the API is technically in a draft mode but it always looked like a really good draft. The more I code against it and use it the more I believe that’s true. Yes, my development speed is increasing as I become more familiar with all the technologies and get past some more technical hurdles but it might take the better part of a man month to finish this up (which is maybe a man-week more than I originally eyeballed).
The progress though has been steady. I had a hiccup late last night with my test harness. The Fuel HTTP library I’m using in Kotlin pushed a new release that requires the 1.30 version of Kotlin, which apparently is harder to come by than I thought. Manually setting the version fixed it all but not until after I spent half an hour fumbling around with it before giving up. Today was the deep dive into the Comments endpoint. As was the case with the previous Likes endpoint Frank’s previous work left a very solid base. Fleshing out the tests for some different errant behaviors, testing error messages as well as codes, and finding problems with the interactions once the test harness interacts with it over HTTP were the usual gremlins to squash. Still, with only two more mostly fleshed out end points to work with coming from Frank’s code base, I have a feeling that the development pace will be slowing down. Maybe I’ll have gained sufficient efficiencies in my speed of coding on all of these to make up some of that difference.
Along with the above gremlins now that it’s being interacted with I am seeing some potential small grained details that need to be discussed about the API. That’s all tracked in the issue tracker on the API documentation page though. Again, this is solid work by the team putting the API together and Frank’s initial code base that I’m starting from.
In summary progress for the day:
- Comments API Endpoint is finished and ready for pull request
- Test harness example of interacting with the Comments API is completed
- Some Issues were submitted to discuss minor changes to the status reporting back from the REST services on things like what happens when a Comment ID doesn’t match the Post ID that the REST endpoint was called with.
- Some small documentation touch ups to address navigation