Our team made it a priority this summer to rewrite our API to better suit the application’s needs as well as provide thorough documentation for our new set up.
Refactoring The Localify API
< ALL POSTS
December, 8th 2020
The original Application Program Interface (API) for our Localify.org app was a bit of a mess. It was developed in an “evolutionary” manner as our frontend and backend were being created. That is, it was never really thought through with good RESTful design principles and it did not include any form of documentation. So, our team made it a priority this summer to rewrite our API to better suit the application’s needs as well as provide thorough documentation for our new set up. Our API refactor was greatly influenced by Spotify’s API, since Localify makes have use of their music information and playlisting resources.
Simple and Complex API Objects
One idea in particular that we inherited from the Spotify API was the idea of having objects. An object might be a user, an artist, a recommendation, an event, etc.
We have simple and complex versions of each object. In certain scenarios, only a small amount of information associated with the object is necessary, so sending the front-end this simplified object efficiently and effectively gets the job done. For example, the simple artist object for The Beatles looks like this:
'name': 'The Beatles',
'tags': ['psychedelic rock', 'classic rock', 'british invasion']
In other scenarios, the frontend requires more, and often nested, information. For example, we might list similar artists or events for a given artist. An example of the complex object for the The Beatles would be something like this:
'name': 'The Beatles',
'tags': ['psychedelic rock', 'classic rock', 'british invasion'],
'name': 'John Lennon',
'name': 'George Harrison',
Incorporating simple and complex objects in our code helps improve the program’s overall simplicity and efficiency. This has also helped in preventing recursive information loops. For example, if we consider an artist A with a list of similar artists including artist B. We would not want to list the similar artists for artist B since it might include artist A, and so on. So in this case, we would provide a complex object for A and then create the list of similar artists with simple artist objects to break the recursive information loop.
Frontend and Backend Collaboration
When brainstorming to determine what information would be sent for each simple and complex object, I worked closely with our team’s lead frontend developer Nic Wands. Together, we identified which pieces of information were essential, which pieces would only be essential in certain scenarios, and which components the frontend never needed to see in order to properly render the web app. This discussion allowed us to pinpoint the data that would be sent for each object’s simplified and complex information.
We identified six objects in particular that we were interested in refactoring to make Localify more efficient. The objects that I worked with the majority of the time were artists, events, scenes, venues, users, and recommendations. Check out our original API Design document if you are interested in seeing which pieces of information we initially chose to include for each object’s simple and complex forms.
Once determining how we wanted our new API to work, we shifted gears towards documentation. We utilized the website Apiary to document each object and each function as well as mockup sample HTTP requests and responses. We organized our functions into categories based on their purpose within Localify. This documentation is beneficial because it will allow future members of our team to easily grasp the format of our API. And hopefully, it will allow future outside developers to utilize our application’s API with clarity.
Most importantly, we have found it to be essential that we stay on top of updating our API documentation. We are always working to enhance Localify and the user experience. When changes are made that impact the structure of the API, it’s important to reflect these changes on our API documentation.
API Design is Important and Essential
Taking on this API refactor was very fulfilling for me. As a new member of the team, it gave me a better understanding of both the frontend and backend of Localify. The process helped me get familiar with the code and feel comfortable making adjustments to both ends of the program. This deep dive into the API helped to strengthen some of my technical skills as well since I have not worked this closely with APIs in the past.
Since taking on this API refactor, I have continued to work to enhance Localify as a full-stack developer, and plan to do so until the end of the year. I am currently looking for a tech internship related to music information retrieval for the upcoming summer. I look forward to taking the skills and knowledge I’ve learned while on the Localify team and utilizing them with my future endeavors.