Design Your Own Style Guide with This Public Workspace Linter
You may have used a code linter to ensure that your code is error-free and readable. Now let’s use a public workspace linter and design a style guide to create a consistent appearance.
Think you have a noteworthy public workspace? If you get a perfect score, you’ll see instructions on how to get featured in Postman’s community of 20 million.
Run the linter
1. Fork the collection from this Developer Experience public workspace by clicking the orange Run in Postman button below. If you also choose to “watch” the collection, you can get notified about updates when new linting rules are added to the collection.
2. Next, plug in your
domain to assess as a collection variable. In the screenshot below, you can see the Stripe team’s domain is
stripedev within the URL.
3. Run the collection in your own workspace. In the screenshot below, you can see Stripe scores 7 out of 9 possible points. Filter on the test failures to see how to improve the score.
In the next section, let’s see what’s happening behind the scenes.
The API workflow
If you forked the collection, you can review the code under the Pre-request Script and Tests tabs for each API call.
GETConfiguration setup: The first request is used to initialize variables that will be used in subsequent calls. For example, if your profile page (determined by `domain` collection variable) contains three workspaces and twp collections, the URLs to those entities are stored in an array (also as a collection variable) to be checked later on. Additionally a maximum potential score is set depending on the items you have displayed on your public profile.
GETTeam profile checker: This request verifies that your team profile is complete. For example, adding a logo, bio, and other meaningful information.
GETWorkspace checker: This request verifies your workspace contains a description. If you have multiple workspaces, Postman will continue looping through this request to check the other workspaces during a collection run.
GETCollection checker: This request verifies your collection(s) include documentation.
GETAPI checker: This request verifies your API(s) include documentation.
- Total Score: It’s the moment of truth! Run the collection to see a score displayed in the test results (and console). Filter on the test failures to see how to improve the score.
Next-level concepts in Postman
If you caught all of that, here are some next-level concepts in Postman:
- Branching and looping: Once you have your API workflow organized into a collection, you can run the collection in its entirety. By default, Postman runs the collection in waterfall sequence. However, you can use
postman.setNextRequest()to control your workflow and loop through a request as many times as you please, like we did in this example by checking only as many collections as we had.
- Dynamic test names: Write dynamic test names for more visibility throughout the collection run. In our example, the total score was created dynamically to display in the runner results. Using template literals, we conditionally set a happy or sad emoji depending on our score.
- Spoof a crawler: When using Postman in the web browser, the HTML you see on the page is rendered by the client. If you paste the URL for a Postman workspace into Postman and send the request, you won’t see the full HTML page that you see in your browser. However, you can update the
User-Agentto mimic a crawler so that the pre-rendered HTML normally sent to search engine bots can be inspected and parsed in Postman.
Note: If you recently published or updated the workspace, the results may not be accurate because the rendered HTML is currently cached and updated every seven days.
Customize the linter according to your own style guide
This is one example of automation to assess how thoroughly your public workspaces are documented. This collection allows you to customize the criteria and enforce your own linting rules by adding more tests and assertions. For example, if you want all collection names to be written in title case, you can do that.
Take a look at the example assertions in the collection, and let us know your favorite linting rules in the comments below.