We review Optic, a tool for auto-documenting and testing APIs

There are few things as important to the API developer experience as API specifications and API documentation. Both provide a vital conduit between the API provider and developer user, expressing critical information on functional aspects of the API.

Since these developer resources are so important, it means this source of truth must be infallible. Unfortunately, many APIs function differently in practice against what they claim in the documentation. This is a core problem that many developers have to figure a solution against at some point in their development process.

Today, we’re going to take a look at Optic, a solution that purports to help establish a trustworthy source of truth, synchronizing the functional and actual behavior of the API itself. Does it do this well? More importantly, does it do this cleanly, or does it only serve to increase the workload for the average developer? Let’s find out…

Optics Stated Use Case

The core issue raised by Optic in justifying their approach is the idea that today’s tools simply aren’t all that developer-friendly. While there are other tools that arguably do improve developer experience when it comes to design and implementation, their main stated issue of difficulty in synchronizing specification, documentation, and practical functionality is certainly a valid one. Yes, it is possible to use modern tools to write OpenAPI files, generate code, create contract tests, etc., but according to Optic, the process of actually doing all of that – even in applications purporting to be “developer-friendly” – is often very haphazard and substandard.

Optic’s solution to this is to change the relationship between the codebase itself and the actual function of said base. Usually, these two items are decoupled – the codebase is iterated upon, and once done, is synchronized to the specification and documentation. At times, the synchronization and documentation can be changed, reflecting this change to the codebase. While this approach is often pretty effective at ensuring changes are documented, it’s still a manual process that requires a developer to initiate the system underneath it all.

Optics solution is to have their offering watch traffic and initiate documentation and specification changes as the actual changes occur. By having the system detect a change by testing the function against the stated value, a sort of “system of mistrust” is created. This system of mistrust can constantly test the documentation and ensure that through this testing, it’s both updated and accurate in terms of the functional outputs related to the codebase which generated it.

Optic calls out some specific use cases for the product, but these can be generally summarized by what it results in. Optic intends to create an easy way to write OpenAPI specifications in minutes, ensure that they are accurate at all times, and to automatically detect when the actual, real-world activity doesn’t match – more to the point, their stated fix also provides a clean, easy, and mostly automated method for updating this internally in an effort to improve the overall developer experience. Optic also offers a relatively robust API analytics tool to track actual real-world use to aid in development; this, paired with code, SDK, and Postman Collections generation, aims to provide a strong value proposition for the developer and user alike. Enforcing rule changes to prevent breaking changes, and providing tooling to support API style guides could elevate a developer offering as a whole.

Also read: Auto-Generating a CLI From an OpenAPI Specification

Example Scenario

As part of its documentation, Optic provides a sample scenario flow to demonstrate just how the system works.

In our example, Optic has noted that a new POST request on the /todos path. When traffic to this path is detected, Optic automatically flagged it for review and pushed it via its UI. Here, we can see Optic showing us these first steps:

Now that we’re in the Optic system, we can start doing some interesting things with the newly marked path. One thing we can do is provide a Path Matcher, which will allow Optic to group similar paths to the same operation. This is a great way to control endpoint sprawl via repeated functions and replicated paths, and more to the point, is a great way to teach Optic what it should expect when dealing with new requests under the same pathing structure.

Now that we’ve defined the path, we should document what the request does. In our case, our path allows a user to add a new entity to the “To Dos” area of the application – as such, the path literally allows one to “Add a new to-do item”, which we’ve added here as the stated request function. Now that this is appended, it will be added to the documentation.

One of the best things that Optic does is operate a differential engine to detect changes when they occur and show what functional differences in activity are represented. In our case, not only was the new function and path detected, a new request body shape was detected as well. “isDone” and “task” were both provided in the request, and as such, Optic requests the ability to add this shape to the specification. Moving forward, this shape can then be used for all requests of this form and type, conforming to the actual activity with the stated specification design.

With all of this done, we can see the summary of the changes pending. We’ve got a new endpoint function flow, a stated request shape, and what the response format and meaning is. From here, if we decide to apply these changes, we can have the specification take on this new information and update itself for future use.

This multi-step use case is an excellent one, and it really exposes just how simple and clean the interface is. Optic also adopts a clean aesthetic and easily understandable methodology in this tool.

Also read: 5 Ways OpenAPI Spurs API Agility

Pros

The best pro that Optic has going for it is the fact that the experience is extremely streamlined. The problem at hand is functionally one of approach and design, and Optic certainly has paid attention to design quality. The UI is intuitive, clean, and efficient, and the guided methodology it uses to aid in the documentation for functions and paths is absolutely fantastic.

The differential system used here is also very good and quite effective for a number of reasons. First and foremost, the obvious value comes with the fact that differences that would otherwise be buried are surfaced to the developer. It seems like a small thing (and more to the point, it seems like an obvious thing to implement), but the reality of modern development is that our codebases are often large, tending to “bury” information underneath overly verbose output and exceedingly complex context. Surfacing this information is vital to good development.

Secondly, this “difference” comparison screen approach is an amazing way to, at a glance, isolate potential problems. Just seeing the difference is ok, but being able to see the difference compared to the expected result allows a one-to-one, side-by-side comparison that enables greater precision and understanding. Again, this might seem like an incredibly simple aspect to include here, but these sorts of “quality of life” improvements for developers takes a “good” tool and elevates it to truly excellent.

Cons

One clear con that comes with using something like Optic is that it moves the onus for sensible development away from the developer. It might seem counterintuitive that a tool meant to ease the life of the developer may result in worse results, but there’s something to be said for the argument that it may enable poor choices. When an API is developed, the documentation that it’s married to should be kept up to date by the very function of planning the API from the ground up. While iterations and side changes absolutely do happen, changes should not be so haphazard and so extreme that it is first documented via Optic.

That’s not to say that adequate planning fixes all the situations in which Optic can shine. As mentioned, these side changes to occur, and Optic is great for that use case. Perhaps the best suggestion, then, is to view Optic not as a solution itself to a core problem, but as a tool that helps aid in the resolution of that problem. In other words, Optic should be used as the “screen” that catches undocumented paths and functions rather than the primary method used to document them.

Of course, this is a largely subjective point to make – if a developer is documenting all of the paths and functions using Optic, then one could argue that the user experience is no different from an API that is well-planned ahead of time. Your mileage may vary, and as with any API tool we discuss, you need to evaluate your situation and figure out if this is a valuable part of your workflow.

Conclusion

Optic is a great tool in the sense that it serves to cleanly unite the logic of the API with its practical implementation. While one could make the argument that Optic is a fix to a problem developers should solve through planning and conscientious development, the reality is that the problem does exist – thus, Optic as a solution should be looked at for what it is in the context of what it does. Under that consideration, Optic is a wonderfully powerful and intuitive solution that enables efficient, clean development.

Whether your use case is unifying documentation with APIs directly or simply catching all outlying development, Optic is a fine choice. What do you think about Optic? Are there any other tools that you feel do the same job better? Let us know in the comments below!