The number of APIs a developer interacts with on a monthly basis has rapidly grown over the last decade. This can be mainly attributed to the growing trust in 3rd party SaaS companies to handle core business processes and the rising clout of microservices, containerization and serverless architectures. Even within established companies, the dozen APIs that ran the business have been split into hundreds of specialized ones.
Writing microservices with a well-defined purview allows different teams to make their own architecture choices, innovate faster, and write code that is far more readable and maintainable. This is a good thing, but all benefits come alongside trade-offs, and for many companies that trade-off is the cost of stitching all these services together.
Teams employ many different approaches, but the problem is the same: learning the shape of each API, documenting that shape and communicating it to other developers has become a prerequisite to connecting services.
The magic tooling almost every developer we spoke with has articulated:
We want this too for the APIs we develop, but when you look at the landscape of tools it's hard to find anything that checks all the boxes.
In order of most to least favorable:
More and more teams have realized the benefits of using integration tests as the spec for their API. On these teams it's common to direct co-workers to
model_controller_test.rb if they need to know how to access certain functionality exposed by the API.
Using tests as the source of truth for your API Spec brings a lot of advantages:
Integration tests have one major drawback -- they don't produce a standard API Spec like a Swagger as an artifact. Without that capability the test files themselves are the reference so you can't display the them in a nice GUI, generate client SDKs, or share them with developers who are not on your team.
The idea of using proxy servers to document APIs isn't particularly novel -- obviously if a proxy sees every request/response pairing it can infer the parameters, headers, schema and possible responses for any endpoint. The time for this technology to gain prominence has arrived as developers have started to trust systems that learn for themselves rather than being explicitly programmed.
The open questions now are both about data.
The answer to both these questions is tests -- specifically the integration tests your team uses as the source of truth. Test environments handle dummy data, interact with mock services, and aren't impacted by the the small latencies adding a proxy introduces. They also run all your API integration tests providing a rich source of data to the proxy on every check-in.
A documenting proxy combines your integration tests into a declarative API Spec that can be output as the API Spec artifact. This gives you and your teammates another incentive to write great tests, because when you do, you get great API documentation for free.
We built Optic (YC S18) because we believe developers shouldn't be allowed to write API docs. Teams should focus on writing great tests and the code that passes them. So we wrote, and open-sourced, Optic to help every team create reliable docs.
optic.yml file to the root of your API repository.
project: myteam/backend-auth-api test: npm run test paths: -/login -/logout -/user/preferences -/user/password -/user/password/reset
Add an Optic test fixture to your repository. These fixtures route your test traffic through an Optic proxy whenever the
optic-watching environment variable is present. The Optic proxy runs locally so none of the test requests or the post-processing is done on the cloud. Find or create a fixture for your codebase here
//psudocode for example fixture if enviroment['optic-watching']: routeThroughProxy(request) else runNormally(request)
Run your tests with Optic to turn your test into API Docs.
testuser$ optic spec All Tests Passed! Analysis Complete! Documented 6 endpoints from 22 tests in 3.905 seconds
Combining solid API integration tests with a documenting proxy makes it possible to generate great API docs from your tests. Once teams can reliably generate accurate API documentation they can start automating even more parts of software development. More ideas on that next time :)
Thanks for reading!