There are scenarios where it may be useful to ignore endpoints. For example, you may have static assets such as
.js files. This traffic may always be safely ignored.
You may also have undesired behavior on an expected endpoint, such as when you’re testing a work in progress locally. You may want to see the traffic, but not commit it until the work is complete. Or, if a bug is introduced, you may want to fix it in code and ignore the bad traffic in Optic.
Optic will start a new capture when the code is rebuilt. When a build of the code fixes the behavior, the undesired diff will no longer appear. We’ll take a look at both of these flows.
If there is traffic that may always be safely ignored, such as
OPTIONS requests to the server or service requests, set them in your
optic.yml file. When Optic observes this traffic, it will be ignored and no diffs will be captured. For example, the
json-server project has a landing page we’ll visit soon. This is a documentation page for reference only, and is not part of the API. We don’t want to document this. It lives at the root of the project, and we can ignore any calls to
/ safely. Navigate to http://localhost:4000 to see this landing page.
The requests used to generate this page will show up in the Optic dashboard. There’s a request to the root, and requests to
/db and assets to render the page.
We can ignore these files by making changes to the projects
optic.yml file. The changes will take effect on reloading the Ooptic dashboard. Details for the
ignoreRequests values are available at Captures: Ignoring API Paths for the curious, though the demo container has another script that will add an ignore rule for
GET requests to the root to the demo’s
ignoreRequests: - GET / - GET POST PUT /db - GET /favicon.ico - GET /script.js - GET /style.css
Run the ignore script in your container:
- Find your container ID. It should be the same as in Changing Shapes, or you can grab its ID again with
docker ps | grep useoptic/optic-demo.
- Run a script to make the necessary changes.
docker exec <container ID> "/root/ignore_requests.sh"
And refresh the Optic dashboard. The landing page requests should no longer appear.
Instead of actually making a code change in the container, we’re just going to walk through this last step in the documentation. Let’s say an error is introduced to your code. For example, maybe when attempting to address new fields to the
GET endpoint, the values other than ID are dropped and don’t make it into the request
Optic will see the code change, and will observe a new interaction with the endpoint. If we attempt to document the endpoint, it will show us that a lot of fields are now missing and ask us how we want to handle this. Of course, we don’t want to handle this at all - this is clearly a bug, and we can fix this very quickly by reverting our code. What happens to the observed interaction?
Optic works on Captures, which cover a single run of the application being observed. When a code change is made and the application recompiled, Optic will observe this and notify you with a modal dialog in the Optic Dashboard that a new capture is observed. For example, when the bug above is reverted and the code restored to its previous state, we’ll be notified of a new capture in the Optic Dashboard. Click Review to move to the newest capture.
Once we move to the newest capture, which is based on the current session of our application with the code issue resolved, the aberrant endpoint diff goes away. That’s because the previous request does not exist in this current session of the application. Running additional
GET requests to the
posts endpoint show that the desired behavior has been restored. As the desired behavior again matches our last documented behavior, no new diffs will appear for review in the Optic Dashboard.
Note that no actions had to be taken in the Optic dashboard, other than clicking to Review the current capture. Optic automatically detected the code change, started a new capture session, and was able to compare the requests in this new session successfully against the last documented behavior. By reverting our code and rebuilding the application, the rest of the capture work happened without manual intervention.
While we’ve covered many topics here, there’s more to see. It’s best to see Optic in action against your own systems and your own evolving code. Check out our installation instructions to get set up in your local environment.