Never would I have imagined I would say this, but Covid-19 is not all bad. During these uncertain times new things came alive. Because what else is there to do than killing time with some software development?
Sitting cosy and comfortable behind my computer screen, with a cup of coffee, eager as a beaver, carefully crafting piece by piece, typing like it’s the end of the world, thinking that this maybe could be the last piece of software you will write. Well that last part is most likely not true, just joking!
Objective
Of course, what is very important in development is to have a clear objective in mind. In 2009 I started working on an audio application (EliteTagger) that now already has the capability to retrieve data from the Discogs API. Now it was time to pull that part out of it so it can be reused by other people in the community.
Maybe first let’s talk about Discogs.
Discogs (https://www.discogs.com) is the de facto standard website if you look for discography of artist, labels, releases. They have a nice marketplace integrated so you can buy and sell very easily. It is a community driven website that wouldn’t exist if there weren’t people contributing and submitting data into the website. To give you an idea on the magnitude of the data it contains, let me show you some stats (taken from https://api.discogs.com).
- release count: 12.803.891
- label count: 1.561.349
- artist count: 7.007.954
Quite impressive, right? The website also provides a REST API for developers so you can interact with the API from any application. There were already some clients available (php, ruby, …) but for Java this wasn’t the case. The clients available also didn’t implement all endpoints so in my opinion it was not very useful. It was time to add a full client for our fellow Java developers. My objective was clear: “Creating a Java client discogs-client-4j”.
When looking into it a bit further, the client should be very easy to bootstrap and use. It should work easily with vanilla and integrate easily with Spring and Spring Boot. Besides that, the necessary documentation and examples should be available so people don’t get lost in the API.
Deadline
Normally I wouldn’t set strict deadlines for myself. But for this one, I had foreseen a span of 2 months to finish it for 99% (maybe I am not the only developer who thinks a project will never reach 100%? Since we lived in lockdown, time wasn’t really on my mind, so I just moved forward and forward and had a blast of fun. Time really flies when you love developing software.
In the end I was happy to set some deadlines as it helped me to complete the project in time. It was the extra push I needed. The project started on the 15th of March and was completed around the half of May. I estimated to have worked around 240 hours on the project.
Elections
Selecting your specific tools is like a little kid in a candy shop buying some candy. It is always nice to start a project from scratch. It gives you a new look on how to maybe do things differently. Maybe you learnt some cool stuff that you want to apply that you couldn’t do before. Now is the opportunity to (re)-select your allies.
Preferred tools:
- language: Java 8 until 11 should be (at least) supported
- build tool: Maven (just for simplicity, adding gradle files too soon
- extra: Spring, Lombok, JSR305 annotations, Jackson, Apache Commons
- version control: Git in conjunction with Bitbucket
- testing: assertj, junit, mockito, selenium + webdriver chrome (to test OAuth flow), Spring integration testing, Spring Boot test
As you can see, a minimum set of tools is used in this project.
For authentication, before I used Scribe as a library but it is too big and it wasn’t very customizable so I opted for writing my own OAuth library (simple and easy to extend). Once we had that in place, it was time to perform the initial commit.
Breakdown
As I was already familiar with the API, it wasn’t very difficult to have a clean breakdown on the project and on how to start.
- Analyze the API documentation: read the documentation over and over to have a context view on what is possible
- Detect the domains: database, image, inventory, marketplace, root, user
- Collect all metadata (enums, settings, etc…) and contracts (interfaces) and put it in an abstraction layer (API)
- Create a BOM (bill of material) to manage your versions and dependencies (always good idea if you don’t want dependencies declared all over the place)
- Implement authentication first (only rely on it through API) as it is required for most request to the API
- Start on most common used domain (in my case database)
- Write unit test case(s) for the endpoint that you will implement (that should initially fail) – unit tests test all possible values
- Implement code until your test succeeds
- Clean up code and refactor (very important step if you want code not left behind in an intermediate state)
- Iterate until all endpoints of the domain are implemented
- Write integration test case(s) to test the API end-to-end – integration tests test contract of the API and verify that your unit tests are doing what they suppose to do with some extras (e.g authentication)
- Iterate until all domains are implemented
- Write necessary documentation and examples
- Add some extra cool stuff: logging aspect, rest template interceptor and some other tools
Final result
After raising the bar pretty much, I was very happy with the end result. Writing a client is so fun and rewarding. Especially when you can use it yourself.You can bootstrap the client in only a few lines of code and implement 2 interfaces (to help you).
You can find the client on the following link: https://bitbucket.org/kristof_debruyne/discogs-client-4j/src/master/
Currently, the API is in review at Discogs and hopefully it will be added to the developers section. Fingers crossed ! In the example module on Bitbucket, you can find more examples on how to use it. Hope it was as fun for you as it was for me !
Sayonara!
Kristof Debruyne
Java Software Crafter
Kristof is an experienced Java Software Crafter at Continuum. Kristof is a very inquisitive person and has an eye for detail, so crafting software is a perfect match. He has a broad knowledge on how to write decent and readable software, with minimum of defects. A tip he can give: Keep It Simple!
