Removed sources and added new documentation (#38)

* Removed sources * New documentation * Typo fixes * Added contributing doc * Update README.md * Update README.md * Update README.md * Added TOCs
forcedotcom · Jan 6, 2021 · 3bb323c · 3bb323c
1 parent 83bd942
commit 3bb323c
Show file tree

Hide file tree

Showing 265 changed files with 325 additions and 10,679 deletions.
diff --git a/.github/workflows/upload-release-assets.yml b/.github/workflows/upload-release-assets.yml
diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md
diff --git a/README.md b/README.md
@@ -1,6 +1,10 @@
+> ℹ️  **January 2021 update:** the collection sources were moved to the Postman API Network.<br/>
+This repository is now dedicated to hosting the setup/contribution documentation and tracking issues.
+
+
 # Salesforce APIs for Postman
 
-A [Postman](https://www.postman.com/) collection of 200+ requests for the following Salesforce APIs:
+A [Postman](https://www.postman.com) collection of 230+ requests for the following Salesforce APIs:
 
 <table>
    <tr>
@@ -25,7 +29,7 @@ A [Postman](https://www.postman.com/) collection of 200+ requests for the follow
    </tr>
 </table>
 
-![Postman screenshot](/doc-resources/postman-screenshot.jpg)
+![Postman screenshot](doc-gfx/app/limits-status-200.png)
 
 Learn more about the Collection:
 - 🎥 [Webinar](https://trailhead.salesforce.com/live/videos/a2r3k000001WFhk/exploring-the-salesforce-apis-with-postman/)
@@ -35,48 +39,22 @@ Learn more about the Collection:
 - This collection is provided as-is. It's not officially supported by Salesforce or covered by SLAs.
 - API documentation is not provided with the collection. Please refer to the [official documentation](https://developer.salesforce.com/docs).
 
-ℹ️ Please [report issues here](https://github.com/forcedotcom/postman-salesforce-apis/issues).
-
-# Installation
-
-1. Download the [latest Postman collection](https://github.com/scolladon/Salesforce-Postman/releases/latest/download/salesforce-apis.postman_export.json) or go to [previous releases](https://github.com/scolladon/Salesforce-Postman/releases). The collection comes as a `salesforce-apis.postman_export.json` file.
-
-1. [Import it in Postman](https://learning.postman.com/docs/postman/collections/data-formats/#importing-postman-data).
-
-# Get started
-
-1. Clone the "Salesforce Template" Postman environment. Never customize the template directly! Always clone it and link the environment created to the target Sandbox, Trailhead Playground (TP), Developer Edition (DE) or production org.
-1. Edit the environment and fill in these variables:
-   - url (login, test or mydomain)
-   - username
-   - password (+ security token if required)
-1. Use your preferred authentication method (SOAP login is very convenient). This automatically fills the endpoint url and access token environment variables for subsequent API calls.
-1. Use any of the API endpoints from the collection.<br/>
-   **Note:** some APIs are just boilerplates (ex : UI API), you need to copy them and customize them (uri + get parameters) according to your need.
-
-# Postman Architecture
-
-## Template Environment
+## Issues and Questions
 
-Salesforce template environment meant to be duplicated for each of your environment. Do not modify it directly
-Environment variable have been designed to be used by the API \endpoint in order to :
+Report issues and ask questions [here](https://github.com/forcedotcom/postman-salesforce-apis/issues).
 
-- Store values from call result (access token, job id, refresh token, etc)
-- Use values as variable in call (url, endpoint, access token, username, password, etc)
-  Postman "Tests" feature is used to parse query result and store environment variables
+## Installation
 
-## Salesforce Preset
+You can use the **Postman desktop app** or the **Postman web UI** to connect to Salesforce with the Salesforce APIs collection. Use the following table to decide which option works best for you:
 
-Predefine header presets meant to be used when creating new API from scratch.
-Allow to have the Authorization header prefilled with the right syntax and environment variable
-Use it when you need to create a new API call from scratch.
+| Installation Option	| Pros	| Cons	|
+| ---	| ---	| ---	|
+| [Option 1: Using Postman Desktop App (Recommended)](install-api-network-app.md)	| - **Fast setup** (approx. 10 minutes)<br/>- No changes required in Salesforce<br/>- Supports all authentication methods	|	|
+| [Option 2: Using Postman Web UI](install-api-network-web.md)	| - **No software installation required**	| - **Longer setup** (approx. 20 minutes) with greater risk of configuration error<br/>- **Requires Salesforce Org configuration**<br/>- Limited support for authentication methods due to CORS browser restrictions	|
 
-## Salesforce Collection
+Regardless of whether you choose the desktop app or the web UI, you can use all of the collection’s requests and your changes are synchronized between the two environments so you can easily switch between them at any time.
 
-Salesforce APIs Postman Collection
-Name of the endpoint and its description are taken from the Salesforce documentations.
-Collections use environment variable in order to partition the variable content per env and easily switch between environment
 
-# Contributions
+## Contributing
 
-[Contribution guidelines for this project](CONTRIBUTE.md)
+Follow [these instructions](contributing.md) to contribute to the collection.
diff --git a/contributing.md b/contributing.md
@@ -0,0 +1,121 @@
+[Back to main page](README.md)
+
+# Contributing
+
+- [About](#about)
+- [Propose Changes](#propose-changes)
+    - [Requirements](#requirements)
+    - [Contribution Guidelines](#contribution-guidelines)
+    - [Create a Public Team](#create-a-public-team)
+    - [Create a Public Workspace](#create-a-public-workspace)
+    - [Fork the Collection](#fork-the-collection)
+    - [Create a Pull Request](#create-a-pull-request)
+- [Pull Changes](#pull-changes)
+
+
+## About
+
+We’re adding new API requests to the collection over time, but you’re welcome to help. The ability to receive community contributions is a guiding principle for the Salesforce APIs collection.
+
+With **Public Workspaces**, you’ll find the same contribution flow that you’re already familiar with in git: forks, pull requests and pulls.
+
+![Contribution schema](doc-gfx/contribution-schema.png)
+
+This is also great news for you even if you do not contribute to the collection because you’ll be able to pull changes from the collection (bug fixes, new APIs...) without having to reimport anything.
+
+
+## Propose Changes
+
+### Requirements
+
+In order to contribute to the collection, you need to:
+- create a public team.
+- create a Public Workspace.
+- fork the collection from the main Public Workspace.
+
+All of this can be done with a Postman free plan.
+
+>⚠️ Warning: you cannot contribute if you install the collection from the Postman API Network (default installation).
+
+
+### Contribution Guidelines
+
+Follow these guidelines when contributing to the collection:
+
+- Stage only what is relevant to what you've done.
+- Never include credentials.
+- Use the API documented names.
+- Add description from the documentation in the Postman descriptions.
+- Provide the description from the documentation for each GET parameters.
+- API calls should work and be parametrized using environment variables:
+  - Authentication API endpoints must use `{{url}}{{site}}` as host.
+  - Other API endpoints must use `{{_endpoint}}` as host.
+- Optional: provide examples.
+
+
+### Create a Public Team
+
+1. Using a browser, [sign up/in to Postman](https://identity.getpostman.com/login)
+1. Open the top-right dropdown and click **Manage Team**
+1. Click **Team Settings**
+1. Enable **Make team profile public**
+1. Click **Save Changes**
+
+
+### Create a Public Workspace
+
+1. Open the **Workspaces** menu and click **New Workspace**
+1. Fill in a name for your workspace
+1. Select **Team** as the visibility
+1. Click **Create Workspace**
+1. Under the **Sharing** section, change the Team workspace’s visibility to **Public**
+
+    ![Change workspace visibility to public screenshot](doc-gfx/web/change-visibility-public.png)
+
+1. Click **Save Changes**
+
+
+### Fork the Collection
+
+1. Navigate to [this link](https://www.postman.com/salesforce-developers/workspace/salesforce-developers/collection/12721794-67cb9baa-e0da-4986-957e-88d8734647e2/fork) to create a fork of the collection
+1. Enter a label for your fork (e.g.: “My fork”)
+1. Select the Public Workspace you create earlier
+1. Click **Fork Collection**
+
+At this point, you can continue the regular installation procedure either [in the Web UI](install-api-network-web.md) or [in the desktop app](install-api-network-app.md). Postman synchronizes your changes between the two environments.
+
+
+### Create a Pull Request
+
+Once you're ready to contribute, follow these steps:
+
+1. Using a browser, [sign up/in to Postman](https://identity.getpostman.com/login)
+1. Navigate to the workspace that holds your collection
+1. Click on the “three dots” icon next to the “Salesforce APIs” collection and select **Merge Changes** from the menu.
+
+    ![Merge changes screenshot](doc-gfx/web/create-pull-request.png)
+
+1. Open the **Changes** tab and review your changes. Make sure you've met the [contribution guidelines](#contribution-guidelines)
+1. Go back to the **Overview** tab
+1. Fill in the title and description fields. Leave the reviewers list empty.
+1. Click **Create Pull Request**
+
+## Pull Changes
+
+Pulling changes requires that you work on a [fork](#fork-the-collection) of the main Public Workspace.<br/>
+Your workspace doesn't need to be public and you don't need a team to pull changes. You can use a personal private workspace.
+
+1. Using a browser, [sign up/in to Postman](https://identity.getpostman.com/login)
+1. Navigate to the workspace that holds your collection
+1. Click on the “three dots” icon next to the “Salesforce APIs” collection and select **Merge Changes** from the menu.
+
+    ![Merge changes screenshot](doc-gfx/web/merge-changes.png)
+
+1. If the master collection has changes, you'll see a yellow banner with a **Pull Changes** link. Click the link.
+
+    ![Pull changes screenshot](doc-gfx/web/pull-changes.png)
+
+1. Review the changes and click **Pull Changes**
+
+
+[Back to main page](README.md)
diff --git a/doc-gfx/app/api-network.png b/doc-gfx/app/api-network.png
diff --git a/doc-gfx/app/auth-status-200.png b/doc-gfx/app/auth-status-200.png
diff --git a/doc-gfx/app/duplicate-env.png b/doc-gfx/app/duplicate-env.png
diff --git a/doc-gfx/app/edit-collection.png b/doc-gfx/app/edit-collection.png
diff --git a/doc-gfx/app/limits-status-200.png b/doc-gfx/app/limits-status-200.png
diff --git a/doc-gfx/app/manage-env.png b/doc-gfx/app/manage-env.png
diff --git a/doc-gfx/app/select-env.png b/doc-gfx/app/select-env.png
diff --git a/doc-gfx/contribution-schema.png b/doc-gfx/contribution-schema.png
diff --git a/doc-gfx/salesforce/cors-finished.png b/doc-gfx/salesforce/cors-finished.png
diff --git a/doc-gfx/web/activate-env.png b/doc-gfx/web/activate-env.png
diff --git a/doc-gfx/web/api-network.png b/doc-gfx/web/api-network.png
diff --git a/doc-gfx/web/auth-status-200.png b/doc-gfx/web/auth-status-200.png
diff --git a/doc-gfx/web/change-visibility-public.png b/doc-gfx/web/change-visibility-public.png
diff --git a/doc-gfx/web/create-pull-request.png b/doc-gfx/web/create-pull-request.png
diff --git a/doc-gfx/web/duplicate-env.png b/doc-gfx/web/duplicate-env.png
diff --git a/doc-gfx/web/export-env.png b/doc-gfx/web/export-env.png
diff --git a/doc-gfx/web/fork.png b/doc-gfx/web/fork.png
diff --git a/doc-gfx/web/merge-changes.png b/doc-gfx/web/merge-changes.png
diff --git a/doc-gfx/web/pull-changes.png b/doc-gfx/web/pull-changes.png
diff --git a/doc-gfx/web/rename-env.png b/doc-gfx/web/rename-env.png
diff --git a/doc-gfx/web/settings-disable-headers.png b/doc-gfx/web/settings-disable-headers.png
diff --git a/doc-gfx/web/settings.png b/doc-gfx/web/settings.png
diff --git a/doc-resources/postman-screenshot.jpg b/doc-resources/postman-screenshot.jpg
diff --git a/install-api-network-app.md b/install-api-network-app.md
@@ -0,0 +1,65 @@
+[Back to main page](README.md)
+
+# Installing via the Postman API Network with the Desktop App
+
+This is the recommended installation option because it is the fastest to set up and doesn’t require changes on your Salesforce org. You’ll import the collection from the Postman API Network.
+
+- [Install the Postman App](#install-the-postman-app)
+- [Import the Collection](#import-the-collection)
+- [Configure the Collection](#configure-the-collection)
+- [Authenticate with Salesforce](#authenticate-with-salesforce)
+
+
+## Install the Postman App
+
+Download and install the Postman app from [this link](https://www.postman.com/downloads).
+
+
+## Import the Collection
+
+1. In the Postman desktop app, click the **New** button
+1. Switch to the **API Network** tab
+1. Search for **Salesforce**
+1. Click **Salesforce Developers**
+1. Click **Run in Postman** to import the collection.
+
+![Network API install screenshot](doc-gfx/app/api-network.png)
+
+
+## Configure the Collection
+
+1. Click on the **Manage Environments** icon
+
+    ![Manage environment screenshot](doc-gfx/app/manage-env.png)
+
+1. Click on the **Duplicate Environment** icon next to the Salesforce Template Environment.
+
+    ![Duplicate environment screenshot](doc-gfx/app/duplicate-env.png)
+
+1. Click on **Salesforce Template Environment Copy**
+1. Rename the environment with something meaningful in relation with your Salesforce org (e.g.: “Playground 1”).
+1. Set values in the CURRENT VALUE column for the following variables:
+
+    | Variable	| Current Value	|
+    | ---	| ---	|
+    | `url`	| Either:<br/>- `https://test.salesforce.com` for sandboxes or Scratch orgs.<br/>- `https://login.salesforce.com` for production, Trailhead Playground and Developer Edition orgs.<br/>- your custom My Domain URL.	|
+    | `username`	| Your username	|
+    | `password`	| Your password	|
+    | `secretToken`	| Your personal [security token](https://help.salesforce.com/articleView?id=user_security_token.htm) (if required by your org)	|
+
+1. Click **Update** and close the environments dialog.
+1. Select your environment from the environment dropdown.
+
+    ![Select environment screenshot](doc-gfx/app/select-env.png)
+
+
+## Authenticate with Salesforce
+
+1. Open the collection’s **Auth** folder and select the **SOAP Login** request
+1. Click **Send**
+
+At this point, if your environment is correctly set up, you should see a `200 OK` status. This means that you have successfully authenticated with Salesforce and that you can now use the other collection’s requests.
+
+![Authenticate screenshot](doc-gfx/app/auth-status-200.png)
+
+[Back to main page](README.md)