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.

Domain is in the URL path following https://www.postman.com/
Domain is in the URL path following https://www.postman.com/

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.

View total score under the last request during a collection run
View total score under the last request during a collection run

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.

  • GET Configuration 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.
  • GET Team profile checker: This request verifies that your team profile is complete. For example, adding a logo, bio, and other meaningful information.
  • GET Workspace 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.
  • GET Collection checker: This request verifies your collection(s) include documentation.
  • GET API 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.
Use template literals to write dynamic test names for more visibility
Use template literals to write dynamic test names for more visibility
  • 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-Agent to 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.

 


What do you think about this topic? Tell us in a comment below.

Comment

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.