Recently I spend a lot of time developing API at Syncano. Different endpoints are always a bit specific and have some custom code, need design, testing, review, documentation...

There are lots of post about how your API should be designed like this and that, but this post will focus on something different.

I want to introduce you to my new API development workflow. It consists of 12 items in a checklist. Oh, checklist, this has to be boring... Right? Actually checklists prove to be quite effective, at least for me.

Why checklists can be a good idea?

The best arguments for them might be:

  • standardization of workflow
  • reduced cognitive load (you don't have to remember about all those things you have to do before finishing your ticket)
  • satisfaction for checking things on a checklist
  • clear indicator of progress

Personally I like noting things down. Writing can help me structure my thinking and gain focus. So do checklists.

12 steps of API development

I grabbed a cup of coffee and written down those particular items. Probably your own list will be a bit different, but you can use this one as a starting point.

  1. You understand requirements
  2. Requirements are written down somewhere (ticket description)
  3. You know what endpoints with which methods should be implemented
  4. You have a clear design
  5. You have written tests for the new functionality
  6. Tests pass
  7. New code is documented
  8. New code is clean and easy to understand
  9. API endpoints are documented
  10. You know who is affected and what are the changes
  11. People who are affected know about the change
  12. Code is reviewed by someone else (code review why and how)

It's quite longish but I can't really throw anything out.

Missing tools

It's not a bug it's a feature

bug

Take a look at points 10 and 11. How do we know that someone is affected? Probably you can agree with me, that breaking compatibility and waiting for complaints isn't usually the best option.

People can get irritated.

I know that it's a bit unrealistic - at least I haven't found anything like that, but I would like to have two kinds of tools:

API differ

This magical API differ would be a tool for analyzing changes made to the API such as:

  • Recognizing what endpoints were in app before my new changes
  • What endpoints are now in my branch
  • What changed in this endpoints

It could be really awesome to have such tool. Probably building it for all the platforms would be completely impossible, but when narrowing down to a specific API framework it starts to look doable.

Tests differ

Another tool I would like to have is test differ.

It will provide you information about changed requirements contained in the tests for the platform by:

  • Running old tests on the new code
  • Running the new tests on the old code
  • Answering questions such as: what are the differences? How tests changed?

I think that it's important to know such things, because we have to much power in our tests.

We can change assertions, change input data to make tests pass or even skip or remove the test (I've seen such things in code review). It would be good to remind us that the actual word which doesn't change so fast.

Summary

I hope that you'll find my checklist useful. I'll probably start implementing them for django and Django Rest Framework, so any feedback is appreciated.