Keep the signal/noise ratio reasonable by ignoring certain paths on your hostname ie the routes that serve HTML, images, js, etc.
Outcome: Learn how to add ignore rules right from within Optic
You should be on Document New Endpoints page with a few URLs captured for resources you do not want in the API documentation:
Not seeing any URLs to document? Capture more traffic and come back to this step
Do you see any paths that you don't want to document? Optic comes with a set of default ignore rules that handle most of the common non-API traffic an API server might handle. You may find there are certain paths or patterns you want to ignore that aren't in the default list. At the bottom of the unmatched URL learning page, we can build ignore rules dynamically. Type any part of the path name and Optic will start making suggestions for ignore rules
Do this ⤵️
- Type part of the path for the endpoint you want to ignore into the Add ignore rule text box.
- Click the corresponding suggestion for the path you want to ignore.
Optic will build an ignore rule to match your pick, and populate the Add ignore rule text box with the proper rule. Beneath the text box, you'll see a list of paths seen in this batch of traffic that match the pattern. The matches let you confirm you have set your ignore rule properly before adding it to your project. Note the rules take both a method (such as
GET) and a path to ignore. This allows ignore rules to be very granular. For example, Optic ignores all
OPTIONS requests by default. Your browser has sent them to your API, though you've never seen them in Optic traffic: we've already shielded you from that noise.
Do this ⤵️
- Check the matches these paths: list to confirm the generated rule meets your intent.
- Click the Add rule button to add the rule.
Optic has now added this rule to the ruleset. Traffic that meets this rule from any session, including this one, will no longer show up in the unmatched URL list. The rule takes place immediately, and the route should disappear immediately. Optic's ignore rules make it easy to cut down on noise so you can document what matters.
The ignore rules can be very selective, down to a single method on a single path. They can also be flexible: Optic can ignore multiple methods on a pattern of paths as well with the same ignore rule textbox. It's nearly as easy to build a rule to ignore a whole branch of your API, such as a service branch that you don't expose to the public, as it is to ignore a single endpoint. You can read more about the details of the if you need more flexibility when ignoring traffic.
- Start entering the branch of the traffic you want to ignore.
- When you want to match all paths under a branch, add the wildcard
- Note the match rules meet your intended ignore rule.
When Optic suggests ignore rules, it is very selective - it generates a rule that starts with the specific method selected, and includes the specific path to the endpoint. When you enter a rule yourself, such as a wildcard rule, you can omit the method at the start of the rule. This will match every rule. It's a great way to catch all traffic, regardless of the HTTP verb. You may optionally include a method if you would like to be more selective.
Do this ⤵️
- Click the Add rule button
With a few quick rules you can remove noisy traffic from your captures going forward. You'll never have to hide this traffic again. It's part of the Optic configuration, and will be shared with your team when you check in your project. If you change your mind in the future, it's also easy to remove ignore rules and reconfigure them.
All of your ignore rules are stored in the
.optic/ignore file in your project root. This file should be checked in with your API specification so they are preserved and shared with your team. Optic will help you build ignore rules in the UI, and you can also safely add, updated, and remove ignore rules right in the ignore file itself. If you check out your
.optic/ignore file after adding some rules in the UI, you should see them show up right away
Do this ⤵️
- Open your project's
.optic/ignorefile with your editor (and theme!) of choices
The ignore file comes pre-populated with rules that should keep common noise out of your unmatched URL list. The rules follow the general pattern of:
- An optional HTTP method (if left out, will match any method).
- A path to ignore, which can include a wildcard
You can find more information under . Check it out, as it gives you additional flexibility over the ignore rules you and your team need to reduce noise and document your API quickly.
Learn how Optic can help you test, share and safely change your API.