Designing RESTful APIs: A Zalando Coder Dojo

How we helped our technology team to learn API design. Plus: Tips!

photo of Dan Persa
Dan Persa

Software Engineer

Posted on Aug 20, 2015

The Zalando Tech team organizes internal Coder Dojos to foster collaboration and soft skills-learning. Dojos encourage us to leave our comfort zones and work together in different configurations, to achieve results faster. They’re fun and challenging for everyone involved.

Our third and most recent coder dojo focused on designing RESTful APIs. One of the fundamental principles of Radical Agility is to take an API First approach to software development, which means creating first-class APIs that are truly RESTful. Designing RESTful APIs might look easy on the surface, but any experienced API designer will warn you that there are many pitfalls. With the Dojo, we wanted to give our team the chance to practice API design and enhance their skills.


Our API Dojo Format

To bring our participants up to speed, we reviewed all of the phases of designing three RESTful APIs — analyzing our design decisions and considering tradeoffs. When designing the APIs, we split the group into smaller groups of different sizes and then asked for feedback on how productive the participants thought they were, based on the size of their group. Productivity decreased significantly when the group reached six people; the larger the group, the more group members tended to concentrate on small, unimportant and time-consuming points, and lose sight of the big picture. In the smaller groups, members realized they could participate more actively in the discussions and find solutions faster.

Another interesting but expected finding was that our people learned the new API-related concepts really quickly. This wasn’t so evident during our first session, as the participants didn’t identify solutions before their time was up. (Timeboxing is a coder dojo rule for us, which participants didn’t like; going forward, we’ll make the first session longer.) The second session, however, brought solutions and compromises as the participants learned to self-organize more efficiently. Suddenly, the “timeboxed” rule was not a problem anymore! By the third session, participants were beating the clock. I liked that the groups adapted so well, and that the “timeboxed” constraint helped them become faster and better.

How to Run Your Own API Coder Dojo

  • How do you replicate our experience? Here are some practical tips: Timebox every activity: This will enable you to try more things and include more sessions.
  • Throw away the code: The goal of a Coder Dojo is to focus on process, not to deliver something. Eliminate pressure as much as possible.
  • Do a retrospective after each session: Practicing is not enough. Learning requires reflecting on what you just did. Sharing your personal experience with the group will help everybody improve.
  • Get feedback from participants: Create a feedback board so that your participants feel more engaged, and so you can improve for next time. The best part about feedback is that it’s free! People are glad to give it—you only have to ask for it. :)
  • Pizza and beer are the secret ingredients: In the morning, engineers are powered by coffee. In the evening, slices and beer fuel us.
  • Make it FUN: If it's not fun, we're doing it wrong!
  • By the end of the Coder Dojo, our participants understood how to successfully tackle and resolve some key API design problems. We also gained a clearer understanding of what distinguishes a mediocre API from a great one.

Looking forward to the next Dojo!

Related posts