← Home

Testing a legacy API

16 December, 2020

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:

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:

Expand and repeat

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

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

Conclusion

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.