Api By Example (ABE) is an approach to testing APIs across microservices by documenting API examples in JSON files in a common format. The ABE files describe API requests and responses and allow frontend and backend teams to work independently while ensuring compatibility. The process involves creating ABE files in a mocks repository, which then become dependencies for the service provider and consumer repositories to reference during development and testing.

1. Api By Example
...an approach to testing across services

2. Before (monolith)

3. The Goal (service-based)
We wanted to split it up:
Smaller specialised services
Backend services: API (Django/DRF)
UI: service consumer (AngularJS)

4. Case in point: the UI
2 teams:
AngularJS single-page app
Django Backend

5. How We Wanted to Work
Both teams able to work independently
UI team should not be blocked by backend team
Both sub-systems testable separately
Backend team should not dictate the API

6. The ABE format
Api By Example
An API is described with example
request/response exchanges
These examples are in JSON files (ABE
format)

7. An ABE
file:
{
"description": "Retrieve a specific user",
"url": "/json/users/[0-9]+",
"method": "GET",
"examples": {
"OK": {
"description": "User response with id of 1",
"request": {
"url": "/json/users/1"
},
"response": {
"status": 200,
"body": {
"id": 1,
"first-name": "Joe",
"last-name": "Bloggs",
"age": 29,
"address": {
"street": "12 Springfield Road",
"county": "Surrey",
"postcode": "SM5 7AQ"
} } } } } }

8. The repos
3 repos:
mocks: API samples
The service provider
The service consumer

9. The process
It all begins with a PR to the mocks
repo:
PR to be OK’d by producer and consumer
PR is a documented discussion of the API
The end ABE files are a documented API
A merged PR -> a new API release

10. Mocks as a dependency
Mocks are a versioned dependency in
producer and consumer
Python-friendly: pip install / requirements.txt
Front-end friendly: bower install / bower.json
A new API release: at least 2 PRs, to producer and
consumer(s), to update version

11. Tooling
ABE-protractor:
Populate a mock backend with ABE samples in
protractor tests
ABE-python
Parse ABE files for usage in API tests
others...

12. Want to contribute?
Still much a work in progress.
Let’s have a chat if you’re interested.
Carles Barrobés
@technomilk
github.com/txels
github.com/apibyexample