Terraform logo

We had an interesting discussion today about testing an existing API to later evolve or fix it.

We all prefer to do some kind of Test Driven Development. But testing the legacy is common in real life, particularly in the context of private API that evolved over the time.

Initially simple, the new needs introduced complexity and regressions. Nobody wants to fund a full rewrite or test suite.

Let me show you a way to get a low cost test harness !

Align before you test …

Make sure that all actors of the API (Business, developers and testers) have a common understanding (and naming) of what your API does or should do.

You will have to share a common model.

Model your API through Event Storming

What you get with event storming

Domain Driven Design is a fine tool to model your data and API. But full Domain Driven Design sessions may sometimes feel a bit overwhelming. I prefer using Event Storming, it is cheap, fast and efficient.

Within only 2 x 1 hour Event Storming, sessions you will have:

  • a common understanding of the business requirements (i.e. what is behind the name of data we create or exchange through the API and how it is used).
  • build the testing scenario (from a business perspective)
  • model of the events and data exchanged by API’s.
  • Identified bounded contexts (a big fancy word for services provided by the API’s)
How to do event storming modeling

This article give a very actionable way to do event storming, even in full remote configurations.

You may ignore the part of the article about event bus if you do no use one, which is perfectly OK for simple use cases.

Main steps to build Event Storming model:

  1. List main events (use past tense verbs like “file uploaded”, “request created”…)
  2. Sequence events in time
  3. List what triggers events (now you have your business scenario)
  4. Regroup events (aggregate) to identify entities, give entities a name.
  5. Find bounded context (i.e. group thing together to avoid event dependencies)
  6. Name and build your services (or API endpoints)

Document the API model with OAS

I will not expand on this, OpenAPI/AOS V3 (former swagger) specification is an absolute must have for REST APIs.

Luckily, it already exists on our API. If it is not your case, you may start here: https://apihandyman.io/

Now test the API

Start with a simple business scenario

Start small to quickly get an idea of the workload to expect later if you want to cover other scenario.

To test an existing (but untested) REST API, I would recommend:

  • have a quick event storming session with business and developer to align everybody on API model.
  • identify 1 simple business scenario
  • write down the scenario and data (text in a wiki will do it).
  • implement the test script versioned with the code. Do not focus on the testing framework. A simple script written in the same language as the application (js, groovy or even curl or powershell) today is better than the perfect tool never.
  • automate it if you can (or automate later)
  • Celebrate ! … and share the word ! You had zero test, now you have one. Others will be far easier to implement.

Expand and repeat

Now that you get more confident with the testing of the API, you can proceed with expanding the tests.

  • expand scope (more complex business scenarios)
  • if you plan refactoring or redesign, try to focus your tests on theses areas.
  • automate the test as part of continuous integration chain
  • automate calculation and publishing of coverage of your tests
  • write the tests before (or when you commit the code)
  • expand to cover non functional requirements
    • security
    • scalability / load testing

Key point of attention

  1. Start small. Do not over engineer your tests or tools.
  2. Be clear about the expectation. You only want to test one or two simple case (for now).
  3. Have a dedicated testing environment from day one. Do not test on the real environment. You have to provision a environment that you can refresh before testing or at least an environment that you can write to safely.
  4. Test data are part of the test, they should also be versioned.
  5. This is a team responsibility. Make sure both business analyst AND developer (or testers) participate to the definition of tests or API modeling.

To go further


Tests help you deliver more value to your users, and save you time.

So the most important thing is to get started now.

I showed you an effective way to create tests on a legacy API.

Alignment is key, so use event storming to build a shared understanding of the API goals. Start with one critical business need, and write tests with simple tools to automate quickly.

You will progressively expand the scope of your tests later.