Skip to content

Latest commit

 

History

History
191 lines (134 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

191 lines (134 loc) · 13.3 KB

Contribution Guide For REST API Playground

Getting Started

Before you begin:

🪲 Issues

If you've found something in the content or the collection that should be updated, search open issues to see if someone else has reported the same thing. If it's something new, open an issue here. We'll use the issue to have a conversation about the problem you want to fix.

🛠️ Pull requests

We handle pull requests in postman.

A pull request is a way to suggest changes in our REST API Playground.

When we merge those changes, they will be available for everyone to see and use.

Ready to make a change? Fork the collection

Fork the collection you want to make changes to.

We recommend forking to a private workspace while you work on your changes. You can move it to a public workspace when you are done making your changes.

The naming convention of the fork is not enforced, however we recommend naming the fork after the folder you are modifying/adding. If you are modifying/adding more than folder name it after the type of change you are making.

If you have your changes in a non forked collection, make the changes in the forked collection. You can do this manually or by dragging and adding/replacing the apis or folders you made changes to/for.

See Contribution Guide for details on the specifics on the conventions and changes you should make.

Done making your changes? Make a pull request

To make a pull request, your forked collection must be in a public workspace. If your forked collection is not in a public workspace, you need to move the collection to the public workspace.

Next follow these conventions for filling out the pull request:

  • Title the pull request apprioriately based on the change being made and follow code of conduct.
  • Have a description of the changes you make so we understand what the pull request is doing.
  • Put MicroStrategy Developer as the reviewer.

Review after submitting the pull request

  • Once you submit your PR, we will review it. But, the first thing you're going to want to do is a self review.
  • After that, we may have questions, check back on your PR to keep up with the conversation.

Your pull request is merged

Congratulations! The whole MicroStrategy community thanks you. ✨

Contribution Guide

As you make changes keep the following in mind:

  1. If the api is not available publicly, we will not add the api workflow in playground.
  2. All the workflow in playground should be ready to use in demo or brand new cloud environment without server side setup.
  3. Exception to (2), if the workflow requires some configuration, we should clearly document the requirement in documentation.

Variables

There are many different types of variables available in postman. In our playground, we use environment variables and local variables.

Environment Variables

Environment variables are scoped to the environment you selected. We provide two environments in our playground. One is the demo environment and the other is a template for a new cloud environment.

In these environments, we provide some long-lived environment variables such as:

  • baseUrl
  • projectId
  • username
  • password
  • loginMode Please use these long-lived environment variables over creating your own, whenever possible. Note: In the template environment, please change these values to suit your environment.

Environment variables are used to store values that may be used across more than one apis or workflows. For PRs that add/modify content from our collections, you can create/edit these variables through pre-request scripts and tests.

For environment variable naming convention and usage:

  • We adopt camelCase for variable names. An example can be dossierId instead of DossierID.
  • We enforce a "rd_" prefix to runtime generated environment variables(set inside test scripts or pre-request scripts). An example can be rd_instanceId. This variable is set in the test script of an instance creation api.
  • We do not have a "rd_" prefix to long-lived environment variables nor using non-runtime environment variables. An example can be dossierId instead of rd_dossierId because we plan to use the provided dossierId in the environment rather than the runtime generated one.
  • There are special rules that apply to each collection
    • In the workflow collection:
      • Use runtime environment variables and long-lived environment variables for the path/params/headers/body of api when possible. An example can be we will want to use rd_dossierId rather than dossierId, because we can not assure the dossierId will work for every workflow. Hence, we want to generate it at runtime rather than using the existing one in environment.
    • In the api collection:
      • Use non-runtime environment variables and long-lived environment variables for GET apis' path/params/headers/body when possible. An example can be using dossierId instead of rd_dossierId and rd_instanceId instead of instanceId. In our pre-request script, we will change the dossierId to rd_dossierId at runtime automatically if dossierId is empty, so you can still set in pre-request or test-scripts the rd_dossierId if the dossierId was not provided in the environment. Meanwhile for rd_instanceId, the instanceId can not be provided in non-runtime(it's different every time) hence the "rd_" prefix.
      • Use runtime environment variables and long-lived environment variable for apis that will edit(POST, PUT, DELETE, PATCH) in path/params/headers/body when possible An example can be using rd_dossierId instead of dossierId for a deletion api, we don't want users accidentally deleting one of the default provided dossiers in environment. Hence, we make them have to manually change it to dossierId or delete a runtime created one.

Local Variables

Local variables are scoped to the api or request script. They are no longer avaiable once the run is complete. In our playground, we use it in the test scripts to simplify and parse response jsons.

For local variable naming convention and usage:

  • Use it when it is only going to be used in that single request/api and if it makes it easier to get the information you want.
  • Have a name that makes sense(no particular requirement).

Folders

  • The title of the folder should be in "Title Case". "This is an Example".
  • Each folder under the collection should have a description describing the contents under it.
  • Folders can have folders nested within it.
  • If the folder is based on an existing page in API docs try to structure it similar to the docs. Though you can simplify workflows if they feel redundant.
  • You can set variables in the pre-request script if it applies to everything in folder.

APIs

  • The title of the API in postman should be in sentence case. "Get this example".
  • In the test script, you can set variables like the id of a response object. And try to have a test script for each api even if not storing variables just to show what is the proper response like "pm.response.to.have.status(201);"
  • Try to label what params or headers are required or not.
  • Have description for each field.
  • Exceptions/special cases:
    • In the workflow collection:
      • The title of api does not need to be the same as in the swagger docs.
      • Use "Login" instead of "Returns Authorization Token"
      • Use "Logout" instead of "Close all existing sessions for the authenticated user"
      • APIs do not need all optional params or headers. This is optional.
    • In the api collection:
      • The title of the api should match the swagger docs.
      • APIs should contain all optional params or headers.

Workflows

  • Workflows, based on existing documentation, should try to match/structure based on the documentation. Workflows, not based on existing documentation, should have a more thorough description. If the workflow cuts across multiple different api families, put the workflow in a folder that pertains most closely to the workflow or create a new folder, if no folder matches it close enough.

  • Workflows should work either in a demo environment or newly created cloud environment. If setup is needed include it in documentation.

  • Don't cause permanent unrevocable changes in a workflow without user explicitly editing the workflow. This means:

    • Most of time you want to create a new object to showcase editing/modification workflow.
    • Delete any created objects at the end of workflow to clean up space.
    • Revert any changes by apis to existing objects at end of workflow.

  • Try to use a folder existing in demo or newly created environment to store newly created objects. Such as publicReportsFolderId in environments or publicObjectsFolderId.

  • All workflows with "Login" api should have "Logout" api, "Logout" should unset all used variables.

Reviewing

We will review every single PR. The purpose of reviews is to create the best content we can for people who use MicroStrategy.

💛 Reviews are always respectful, acknowledging that everyone did the best possible job with the knowledge they had at the time. 💛 Reviews discuss content, not the person who created it. 💛 Reviews are constructive and start conversation around feedback.

Self review

You should always review your own PR first.

For changes, make sure that you:

  • Pull the latest changes from the source to confirm the changes will have the expected behavior(folder order, etc...). This helps spot issues like typos and content that doesn't follow the contribution guide.
  • Review the content for technical accuracy.
  • Run the API or workflow in Postman in a demo or new cloud environment.
  • Check if the API or workflow is available publicly or on demo server yet. If it isn't the PR will not be approved. In situations, where the api or workflow is available publicly but not on the demo server yet, it will only be approved if it does not cause breaking changes to the existing APIs or workflow that runs on the demo server.

Comments

We may ask for clarification or changes in the comments on the PR in postman.

As you update your PR and apply changes, mark each comment as resolved.