Merge branch 'develop' into articles/prism/mocking.md

* develop: (79 commits)
  Update security-schemes.md
  Update api-operations.md
  Add Spec Validation (#117)
  Add File Validation (#116)
  Add Editor Configuration (#118)
  Update blocks.md
  Update subpages.md
  Update pages.md
  Update pages.md
  Update pages.md
  Update routing.md
  Update managing-headers-footers.md
  Update working-with-files.md
  Update sign-in.md
  Update edit-profile.md
  Update manage-password.md
  Update deactivate-account.md
  Update changing-your-email.md
  Update create-project.md
  Update sign-out.md
  ...

TOC.md

@@ -1,4 +1,12 @@
-* Platform
+---
+title: Stoplight Help
+description: 'Bout time.
+theme: ./theme.css
+javascript: ./global.js
+nav: [['Platform'], [], ['Editor']]
+---
+
+* ![Platform](./logo.png "Platform")
   * Getting Started
     * [What is Stoplight?](./articles/getting-started/what-is-stoplight.md)
     * Getting started for new users

articles/accounts/changing-your-email.md

@@ -1,4 +1,4 @@
-# Change Your Email Address
+# Change your Email Address
 
 ![](/assets/gifs/account-info.gif)
 

articles/accounts/changing-your-username.md

@@ -1,6 +1,6 @@
 # Change Your Username 
 
-![](/assets/gifs/account-info.gif)
+![](../../assets/gifs/account-info.gif)
 
 ## What 
 You can change your username at any time 

articles/accounts/deactivate-account.md

@@ -4,5 +4,5 @@
 * We're sorry to see you leave. Come back soon! 
 
 ## How
-1. Email [support@stoplight.io](http://) with your deactivation request 
+1. Email [support@stoplight.io](mailto:support@stoplight.io) with your deactivation request 
 2. We'll take care of the rest 

articles/accounts/edit-profile.md

@@ -1,6 +1,6 @@
-# Edit Your Profile 
+# Edit your Profile 
 
-![](/assets/gifs/account-info.gif)
+![](../../assets/gifs/account-info.gif)
 
 ## What 
 * In your profile you can edit things like: 
@@ -12,11 +12,11 @@
     * Change Password 
  
 ##  How
-1. Select your **Username** in the top right corner. 
+1. Select your **Username** in the top right corner
 2. Click **Account**
 3. Make your edits in **Basic Info** then click **Save** 
     * You can also click **Reset** if you would like to start from scratch 
 4. Upload a profile image 
-5. Make your edits in Change Password then retype it then click **Change Password** 
+5. Make your edits in Change Password then click **Change Password** 
     * Password must be at least 6 characters 
  

articles/accounts/manage-password.md

@@ -1,9 +1,9 @@
 # Manage Your Password 
 
-![](/assets/gifs/account-info.gif)
+![](../../assets/gifs/account-info.gif)
 
 ## What 
-* If you’ve forgotten the password you use to sign into Stoplight, you can easily reset it at any time
+* If you’ve forgotten the password you use to sign in to Stoplight; you can easily reset it at any time
 
 ## What
 1. At the login page select **Forgot Password?**

articles/accounts/sign-in.md

@@ -18,7 +18,7 @@
 1. Click on **Join**
 2. Fill in your **Name** 
 3. Create a **Username** 
-4. Fill in the **Email** you want associated with this account 
+4. Input the **Email** you want associated with this account 
 5. Create a **Password**
     * Password must be more than 6 characters 
 6. Click **Join Stoplight**

articles/accounts/sign-out.md

@@ -1,9 +1,9 @@
-# Sign Out Of Stoplight 
+# Sign Out of Stoplight 
 
-![](/assets/gifs/sign-out.gif)
+![](../../assets/gifs/sign-out.gif)
 
 ## What 
-* By default Stoplight remains open so if you wish to sign out follow these quick and easy steps 
+* By default, Stoplight remains open. If you wish to sign out follow these quick and easy steps 
 
 ## How
 1. Click on your **username** in the top right corner 

articles/desktop/overview.md

@@ -1,15 +1,33 @@
-# Web & Desktop App
-
-Stoplight has a desktop app! Download the appropriate version here (link).
-
-## Web or Local?
-The main difference between the Stoplight desktop app and the web app is that the desktop app can store requests and test data offline. It can also connect with APIs that are behind firewalls or otherwise not available on the public internet (localhost as well).
-
-## Local Prism
-When you start the Stoplight desktop app, it will start an instance of Prism on http://localhost:4010. This is same as if you downloaded the Prism binary, opened your terminal, and started prism manually. When you run local tests in the desktop app, it takes care of calling a local instance of Prism with the correct arguments and spec files.
-
-## Local Save
-* The Stoplight desktop app can read/write specification files on your local file system. This is perfect if you generate your specification outside of Stoplight (like from code), want to use version control systems like Git, or want to use your favorite IDE to work on the spec. 
-* This feature is **NOT** available in the web app 
-
-
+# Web & Desktop App
+
+
+Stoplight has a desktop app! Download the appropriate version [here](https://stoplight.io/download) .
+
+
+## Web or Local?
+
+
+The main difference between the Stoplight desktop app and the web app is that the desktop app can store requests and test data offline. The desktop app can also connect with APIs that are behind firewalls or otherwise not available on the public internet (localhost as well).
+
+
+## Local Prism
+
+
+When you start the Stoplight desktop app, it will start an instance of Prism on http://localhost:4010. The desktop Prism instance is identical to the downloadable Prism binary run manually from your terminal. When you run local tests in the desktop app, it automatically calls a local Prism instance with the correct arguments and spec files.
+
+
+## Local Save
+
+
+* The Stoplight desktop app can read/write specification files on your local file system. This is perfect for generating specification outside of Stoplight (like from code), want to use version control systems like Git, or want to use your favorite IDE to work on a spec. 
+* This feature is **NOT** available in the web app 
+
+
+
+
+ the web app 
+
+
+<!--stackedit_data:
+eyJoaXN0b3J5IjpbMTU3NDc5MjY0XX0=
+-->

articles/editor/editor-configuration.md

@@ -1 +1,35 @@
+# Configuration with the `.stoplight.yml` File
 
+This document describes the usage of `.stoplight.yml`, the file that is used by the Stoplight editor to manage its configuration.
+
+It is placed in the root of your project and allows you to configure editor settings and environments that will apply to **all** users of the project. This allows you to share commonly-used settings between members of your team directly.
+
+You can make changes to the `.stoplight.yml` file by opening it:
+
+![](../../assets/images/editor-configuration.png)
+
+### Editor Configuration
+
+- **defaultFile**: The `defaultFile` setting allows you to control which file is displayed to read-only users when they navigate to the project. This can be useful to show them a particular markdown or hub on first load.
+
+### Environments
+
+![](../../assets/images/editor-configuration2.png)
+
+Environments make it easy to auto-populate variables (hostnames, ports, passwords, etc.) used by specifications and scenarios. Read more about them [here](../testing/variables-environment.md).
+
+The environments and variables defined in the `.stoplight.yml` are shared amongst all users, which makes this a good place to define common or shared variables, such as the url host for a particular API + environment. 
+
+There are three environments included with a new project:
+
+* __Default__ - The __Default__ environment is used by the Stoplight editor when first logging in and if no other environment has been selected. This is commonly used for variables needed for development and prototyping.
+* __Staging__ - The __Staging__ environment is automatically created for the storing of"staging" or "pre-production" variables and settings.
+* __Production__ - The __Production__ environment is automatically created for the storing of production variables and settings.
+
+These environments can be customized by editing the `environments` key of the `.stoplight.yml` file. To add a new environment, simply add a new key to the `environments` property, and set the value to an empty object or an object with default variables to share amongst your team.
+
+***
+
+**Related**
+
+* [Testing Environment Variables](../testing/variables-environment.md)

articles/editor/environments.md

@@ -1 +1,25 @@
+# Environments
 
+![](../../assets/gifs/editor-configuration.gif)
+
+The Stoplight editor includes an embedded configuration system that can be used to auto-populate environment information and other variables (hostnames, ports, passwords, etc.) utilized by specifications, scenarios, or collections. To setup the editor configuration, click the icon towards the top right of the editor screen immediately to the left of your username.
+
+![](../../assets/images/editor-configuration.png)
+
+## Private Variables
+
+The left-half of the configuration window is dedicated to "Private Variables", which are variables that are _only_ stored locally on your system and are never sent to Stoplight. Private Variables should be reserved for secrets specific to you, such as user-specific passwords, API keys, and other pieces of sensitive data.
+
+## Resolved Variables 
+
+The right-half of the configuration window displays "Resolved Variables", which is a read-only view of the variables currently exposed to your editor based on your current environment. These variables are stored in the `.stoplight` file included in your project (under "Config" in the File Explorer). To update the default or environment-specific variables stored in Stoplight, click the "Manage Environments" button under the configuration window.
+
+![](../../assets/gifs/editor-configuration2.gif)
+
+Variables stored in your configuration are in JSON, and can be referenced using the following format:
+
+```
+{$$.env.myVariable}
+```
+
+Where `myVariable` is the name of the variable in your configuration.

articles/editor/file-validation.md

@@ -1 +1,27 @@
+# File Validation
 
+![](../../assets/gifs/file-validation-OpenAPI-spec.gif)
+
+File validation is the process of checking a file's syntax and structure to make sure it meets specific requirements. Stoplight's validation ensures file edits are in the correct format. This is especially helpful while editing structured file formats (e.g. OpenAPI documents) so that any errors can be resolved quickly and efficiently.
+
+File validation is run after every file edit to make sure no errors were introduced. A notification will appear if validation errors were introduced so that they can be resolved before attempting to save. If a validation error is detected, an alert will appear with an explanation of the issue and where it occurred.
+
+![](../../assets/images/file-validation-error-overview.png)
+
+Validation failures come in two levels:
+
+* __Warnings__ - A warning is generated if the validation process found a non-critical issue that did not interrupt the processing of the document. As an example, inclusion of non-standard fields in an OpenAPI document will display as a warning.
+
+* __Errors__ - An error is generated if the validation process found a critical issue that prevented the processing of the document. As an example, not including the correct fields in an OpenAPI document will display as an error.
+
+Different types of file validations are used throughout the Stoplight platform. At a high level, file validations aim to identify the following two groups of errors:
+
+* __Syntax__ - Most files stored in Stoplight are either JSON or YAML format, so they must always adhere to the JSON/YAML formatting standards. If anything typed into the editor does not meet the format criteria, it will be rejected with a notification pointing to where the syntax error occurred. _Syntax errors will prevent the file from being saved until all errors are resolved._
+
+* __Correctness__ - Certain files stored within Stoplight must adhere to high-level specifications to ensure they are able to be read and processed correctly. The OAS/Swagger specification is one such standard. It is critical that every OAS document stored in Stoplight meet these standards. If an error is detected in any document, either an error or warning will be generated with a description of the issue.
+
+***
+
+**Related**
+
+* [OpenAPI Validation](../modeling/openapi-validation.md)

articles/editor/working-with-files.md

@@ -12,13 +12,13 @@ As part of our effort to make the Stoplight platform more flexible and familiar
 
 ## File Explorer 
 
-WIthin the file explorer you can:
+Within the file explorer you can:
  
-* Search for Files
-	* Search for files using the search bar at the top of the file explorer 
-* Create Files 
-	* Hover to the right of the filetype headers and click the + to create a new file 
-* Export Files 
-	* Hover to the right of a file and click the arrow to export files into OAS
-* Delete Files 
-	* Hover to the right of a file and click the trash can to delete files
+* **Search for Files**
+	* Search for files using the **search bar** at the top of the file explorer 
+* **Create Files** 
+	* Hover to the right of the filetype headers and click the **+** to create a new file 
+* **Export Files** 
+	* Hover to the right of a file and click the **arrow** to export files into OAS
+* **Delete Files** 
+	* Hover to the right of a file and click the **trash can** to delete files

articles/getting-started/faq.md

@@ -1,32 +1,51 @@
 # FAQs
 
-## General 
+## General
 
-* Is Stoplight v2 being discontinued
-	* No! We love old stuff! Stoplight Classic (v2) will persist but support will transition towards Stoplight NEXT with major bugs continuing to be addressed. We encourage all our Stoplight Classic (v2) users to move onto our new platform.  
-* Can I save my files locally?	
-	* Yes, but only on the desktop app. To learn more click here (link). 
-* Is there a way to manage multiple APIs in a single Project?	
-	* Yes. In Stoplight Next you can manage unlimited APIs in a single Project. To learn more click here (link). 
-* What are the differences between Stoplight Classic and Stoplight NEXT? 	
-	* Stoplight Classic is our original platform. Stoplight NEXT is the next generation of platform, including all the features and tools from Stoplight Classic and much more. To learn more click here (link). 
-* Can I transfer Account ownership? 
-	* Yes, you can [transfer ownership of an Organization](https://next.stoplight.io/stoplight/stoplight-next-docs/blob/master/Stoplight%20Platform.hub.yml?edit=%23%2Fpages%2F~1%2Fdata%2Fchildren%2F2%2Fdata%2Fchildren%2F5) or [make changes to your personal account](https://next.stoplight.io/stoplight/stoplight-next-docs/blob/master/Stoplight%20Platform.hub.yml?edit=%23%2Fpages%2F~1%2Fdata%2Fchildren%2F0%2Fdata%2Fchildren%2F1) 
-* Is there a way to edit swagger directly?	
-	* Yes. In Stoplight NEXT you can switch between the GUI editor and the source code via a TAB in the editor.For more information click here (link).
-* Does Stoplight offer monitoring solutions?	
-	* Not at the moment, however, scheduled scenarios (monitoring) is on our roadmap. 
-* Does Stoplight support SSO?	
-	* Yes. As part of an on premise install against LDAP/AD (link).
-* I am looking for a secure solution for hosting my API and restricting access, what do you recommend for hosting?	
-	* Stoplight offers an on-premise Enterprise Product that will meet most security needs (link). 
-* How do I migrate my Stoplight files to Stoplight NEXT?
-	* Export your old Projects. Copy and paste the generated JSON into Stoplight NEXT (link).
-* Does Stoplight support OAS 3? 
-	* Currently we support OAS 2 with OAS 3 on our immediate roadmap.  
-* My singup token has expired, how do I generate a new one? 
-	* On the login page go to forgot password and reset it using your email. This will renew your token. 
-* Can I remove the Stoplight branding from my API docs? 
-	* Yes! In Stoplight NEXT all paid users have access to the underlying CSS. 
+**Is Stoplight v2 being discontinued?**
 
-  
+Stoplight Classic (v2) will persist, but new feature development will only occur on Stoplight v3. Major bugs in Stoplight v2 will continue to be addressed. We encourage all our Stoplight Classic (v2) users to move onto our new platform. Read more about migrating from v2 to v3 [here](LINK).
+
+**Can I save my files locally?**
+
+Yes, but only on the desktop app. Click [here](LINK) to learn more about the Stoplight desktop app.
+
+**Is there a way to manage multiple APIs in a single Project**
+
+Yes. In Stoplight v3 you can manage unlimited APIs in a single Project. To learn more click [here](LINK).
+
+**What are the differences between Stoplight Classic (v2) and Stoplight v3?**
+
+Stoplight Classic is our original platform. Stoplight v3 is the next generation of platform, including all the features and tools from Stoplight Classic and much more. To learn more, click [here](LINK).
+
+**Can I transfer Account ownership?**
+
+Yes, you can [transfer ownership of an Organization](https://next.stoplight.io/stoplight/stoplight-next-docs/blob/master/Stoplight%20Platform.hub.yml?edit=%23%2Fpages%2F~1%2Fdata%2Fchildren%2F2%2Fdata%2Fchildren%2F5) or [make changes to your personal account](https://next.stoplight.io/stoplight/stoplight-next-docs/blob/master/Stoplight%20Platform.hub.yml?edit=%23%2Fpages%2F~1%2Fdata%2Fchildren%2F0%2Fdata%2Fchildren%2F1)
+
+**Is there a way to edit my OpenAPI (Swagger) directly?**
+
+Yes. In Stoplight v3 you can switch between the GUI editor and the source code via a TAB in the editor.For more information click [here](LINK).
+
+**Does Stoplight offer monitoring solutions?**
+
+Not at the moment, however, scheduling scenarios + alerting (monitoring) is on our roadmap.
+
+**Does Stoplight support SSO?**
+
+Yes. The business and enterprise plans support SSO. For more information, click [here](LINK).
+
+**I am looking for a secure solution for hosting my API and restricting access, what do you recommend for hosting?**
+
+Stoplight offers an on-premise installation option that will meet most security needs. For more information, click [here](LINK).
+
+**Does Stoplight support OpenAPI 3?**
+
+Currently we support OpenAPI 2 (Swagger 2). OpenAPI 3 support on our short term roadmap.
+
+**My sign-up token has expired, how do I generate a new one?**
+
+On the login page, go to forgot password and reset it using your email. This will renew your token.
+
+**Can I remove the Stoplight branding from my API docs?**
+
+Yes! In Stoplight v3 all paid users have access to the underlying CSS, and can customize it to remove or change any of the visual elements on the page. Click [here](LINK) for more information on themeing.

articles/getting-started/what-is-stoplight.md

@@ -22,7 +22,7 @@ Once you have your API design / documentation, how do you make sure that it rema
 You have your API designed and documented privately in the Stoplight app, and now you want to share all or part of it with 3rd parties (developers, customers, clients, etc). Stoplight makes it easy to publish your documentation to the world, with a single click.
 
 
-![](../../assets/images/hubs-overview.png)
+![](../../assets/images/HubsPreview.png)
 
 ## Mock Server
 Stoplight provides a complete mock server for every API described in the app. Run tests against this mock server, build consumers (like mobile apps, SDKS, etc) before the final API is ready, and more.

articles/hubs/blocks.md

@@ -1,4 +1,8 @@
 # Blocks 
+
+![](../../assets/gifs/Blocks.gif)
+
+## What
 Blocks are the micro-level building blocks of Hubs. They house multiple forms of content and allow for simple restructuring and modification. 
 
 <callout> Hovering over a Block reveals additional tooling including: Preview, Cut, Copy, Reference External Source, and Delete </>
@@ -19,11 +23,11 @@ Blocks are the micro-level building blocks of Hubs. They house multiple forms of
 ### Callout 
 * A text block with color for emphasis 
 ### Hero 
-* A large stylized text block with extra optional functionality typically found on landing pages 
+* A large stylized text block with additional functionality typically found on landing pages 
 ### Bar List 
 * A navigational block composed of bars with buttons 
 ### Card List 
 * A navigational block composed of cards with text, buttons, and optional images
 ### HTML 
-* Include arbitrary HTML in your hubs, when the other base block types don't quite do the trick
+* Include arbitrary HTML in your hubs when the other base block types don't quite do the trick
 

articles/hubs/managing-headers-footers.md

@@ -1,6 +1,8 @@
 
 # Managing Headers and Footers 
 
+![](../../assets/gifs/headers-footers.gif)
+
 ## What 
 You can customize the headers and footers of your Hub to add additional navigation to your documentation. You can modify a header and footer: 
 
@@ -16,15 +18,15 @@ You can customize the headers and footers of your Hub to add additional navigati
 ### Modify Existing Header and Footer
 
 1. Select the Hub you wish to modify
-2. Click on the Editing toggle 
+2. Click on the **Editing toggle** 
 3. By default, there will already be three headers (Home, API Reference, Help) and a footer (Home) 
-    1. Hover over one of the headers or footers and click on the gear icon to modify 
+    1. Hover over one of the headers or footers and click on the **gear icon** to modify 
     2. Drag the header or footer to another location to change its location 
 
 
 ### Create New Header and Footer 
 
 1. Select the Hub you wish to modify 
-2. Click on the Editing toggle
+2. Click on the **Editing toggle**
 3. Hover over the left or right edge of the header or footer 
-    1. Click on the + button 
+    1. Click on the **+** button 

articles/hubs/pages.md

@@ -1,5 +1,8 @@
 # Pages 
 
+![](../../assets/gifs/create-pages.gif)
+
+## What
 Pages are the macro level building blocks of a Hub. They function as the canvas on which all other Hubs objects reside. They are commonly used as a way to separate information based on the broadest topics. 
 
 ### Hubs Architecture from Top Down 
@@ -15,13 +18,13 @@ Pages are the macro level building blocks of a Hub. They function as the canvas
 ### Create a New Page
 
 1. Select the Hub you wish to modify 
-2. Click on Toggle Editor 
-3. Select + Page in the editor toolbar 
-    4. Input a Page Title 
-    5. Input a Page Route (optional) 
-    6. Power the Page with an External Data Source (optional) 
+2. Click on **Toggle Editor** 
+3. Select **+** Page in the editor toolbar 
+    1. Input a **Page Title** 
+    2. Input a **Page Route** (optional) 
+    3. **Power the Page** with an External Data Source (optional) 
 
-<callout> Did you know? After creating a new page; a header link will automatically be generated </callout> 
+<callout> Did you know? After creating a new page; a header link will automatically be generated </> 
 
-<callout> To add content to a page you must add a subpage or a content block </callout>   
+<callout> To add content to a page you must add a subpage or a content block </>   
 

articles/hubs/ref-other-sources-hubs.md

@@ -1,4 +1,8 @@
 # Reference Other Sources
+
+![](../../assets/gifs/ref-other-sources-hubs.gif)
+
+## What
 Hubs allows you to reference other sources to automatically populate your Hub with content. We call this “powering” a building block. You can power a building block with a file from the current file, a file from the current project, a file from another project, or a file from an external source. 
 
 ### What can I Power

articles/hubs/routing.md

@@ -1,6 +1,8 @@
 
 # Routing 
 
+![](../../assets/gifs/routing-hubs.gif)
+
 ## What 
 Stoplight’s Hubs features an easy to use routing system to make sure your docs have identifiable and friendly URL’s. The routing system allows customization of the following objects: 
 
@@ -13,7 +15,7 @@ Stoplight’s Hubs features an easy to use routing system to make sure your docs
 <callout>Tips for Friendly URL’s 
 
 Friendly URLs are links that are easily readable, rememberable, and relevant to the content.
-Take a look at the URL for this page. Instead of something like https://help.stoplight.io/docs/fnIenof/123, it is https://help.stoplight.io/docs/hosted-documentation/create-friendly-urls, which is much nicer. <callout>
+Take a look at the URL for this page. Instead of something like https://help.stoplight.io/docs/fnIenof/123, it is https://help.stoplight.io/docs/hosted-documentation/create-friendly-urls, which is much nicer. </>
 
 ## How 
 

articles/hubs/subpages.md

@@ -1,5 +1,9 @@
 # Subpages 
-Subpages are the second tier macro building blocks of Hubs. They function as a canvas for blocks. They are commonly used to house content based on a specific topic.  Subpages can have more subpages nested underneath them, which gives you lots of flexibility to organize your hub as you see fit. If a subpage has subpages nested inside of it, it will be displayed as a collapsible group in the left sidebar
+
+![](../../assets/gifs/create-subpages.gif)
+
+## What
+Subpages are the second tier macro building blocks of Hubs. They function as a canvas for blocks. They are commonly used to house content based on a specific topic.  Subpages can have more subpages nested underneath them, which gives you lots of flexibility to organize your Hub as you see fit. If a subpage has subpages nested inside of it, it will be displayed as a collapsible group in the left sidebar.
 
 ### Hubs Architecture Top Down
 - Pages 
@@ -13,12 +17,12 @@ Subpages are the second tier macro building blocks of Hubs. They function as a c
 ### Create a New Subpage 
 
 1. Select the Hub you wish to modify 
-2. Click on Toggle Editor 
-3. Select + Subpage in the editor toolbar
-    1. Input a Subpage Name 
-    2. Modify the Subpage Route (optional) 
-    3. Give the Subpage a SIdebar Token (optional) 
-    4. Power the Subpage with an External Data Source (optional) 
+2. Click on **Toggle Editor** 
+3. Select **+ Subpage** in the editor toolbar
+    1. Input a **Subpage Name** 
+    2. Modify the **Subpage Route** (optional) 
+    3. Give the Subpage a **Sidebar Token** (optional) 
+    4. **Power the Subpage** with an External Data Source (optional) 
 
 <callout> Subpages populate the navigational sidebar of a page. </>
 

articles/modeling/api-operations.md

@@ -1 +1,90 @@
+# API Operations
+## Introduction
+API operations describe the way you define how an API is exposed to a user. Properly defined operations are fundamental to the API development life cycle and the outcome is a final product that is easy to understand and use. Creating a properly designed RESTful API requires research, analysis, and planning. It is the API developer’s responsibility to ensure that the API design, resources, and connected operations are easy to understand by consumers. The following characteristics are true of well-designed APIs: 
+
+- Comprehensive, yet succinct 
+- Understandable and easy to use
+- Supports delta (incremental) development
+- Expedites and simplifies the API documentation process 
+
+## Key Terms
+- A **resource** is an entity or object that has data linked to it, relationships to other objects or entities, and a set of methods that operate on it to access, use, or manipulate the associated data. When resources are grouped together, it is called a collection. 
+- A **Uniform Resource Locator (URL)** is used to indicate and identify the location of an API resource and perform some actions to it. Note that the base URL is the constant part of this location. 
+- **GET** method requests data from a resource and the body of the response message holds the information requested.  
+- **PUT** method requests the server to update the resource or create it (if it does not exist) and the body of the request message indicates the resource to be updated or created.
+- **PATCH** method performs a partial update on a resource and the body of the request message indicates the change to be applied.  This can occasionally be more efficient than PUT because the client forwards changes required and not the entire details about the resource. 
+- **POST** creates a new resource and the body of the request message indicates the details of the new resource to be created. This method can be used to activate operations that will not create a resource.
+- **DELETE** method requests that the specified resource be removed.
+
+## Best Practices
+
+### Resource URL should be based on nouns and not verbs
+
+For example, to retrieve pet details for a pet store which has different kinds of pets:
+
+- /pets (Good) 
+- /getAllPets (Bad)
+
+<!-- theme: info -->
+> A good resource URL contains resources (nouns) and not actions or verbs. Ensure that the resource is in the plural form at the API endpoint.
+
+### Use HTTP methods to operate on resources
+
+To add, delete, or update information, use the HTTP methods GET, POST, DELETE, PUT, and PATCH (also known as verbs). For example:
+
+- GET /pets (returns the list of all pets)
+- GET /pets/5 (returns details of pet 5)
+
+<!-- theme: info -->
+> A successful GET method normally returns a HTTP status code of 200 (OK) and 404 (Not found) if the resource cannot be located.
+
+| GET                                   | PUT/PATCH                                     | POST                                | DELETE                                      | Resource               |
+|---------------------------------------|-----------------------------------------------|-------------------------------------|---------------------------------------------|------------------------|
+| Return list of all pets               | Update all pets                               | Add a new pet                       | Remove all pets                             | path/pets              |
+| Return details of treatment for pet 5 | Update all treatment for pet 5                | Add new treatment details for pet 5 | Remove all treatments associated with pet 5 | path/pets/5/treatments |
+| Returns details for pet 5             | Updates details for pet 5 assuming it exists  | Error (Not permitted)               | Deletes pet 5 details                       | path/pets/5            |
+
+### Make use of a Query String (?) for complex parameter optional parameters
+When you need to add more complexity and dynamics to the request, add parameters to the query string. For example:
+
+- GET /pets?type=feline&age=5 (Good)
+- getFelinePets (Bad)
+
+### Utilize HTTP Status Codes 
+A user should know the status of request made through an API. This might include failed, passed, or invalid responses. The table below summarizes the codes.
+
+| 2xx Success                                                             | 3xx Redirect          | 4xx Client Error | 5xx Server Error          |
+|-------------------------------------------------------------------------|-----------------------|------------------|---------------------------|
+| 200 Ok (Success for GET, PUT, or POST)                                  | 301 Moved Permanently | 400 Bad Request  | 550 Internal Server Error |
+| 201 Created                                                             | 304 Not Modified      | 401 Unauthorized |                           |
+| 204 No Content (Request successfully processed but returns not content) |                       | 403 Forbidden    |                           |
+|                                                                         |                       | 404 Not Found    |                           |
+
+- Be wary of using too many status codes and confusing the API user.
+- It is good to provide an additional description of the status code in the body of the HTTP Response. For example:
+    - Request: method GET /pets?type=feline
+    - Response: 
+```   
+   //This is an invalid request.
+    {
+    "message": "Invalid Pet Type please enter a valid pet category",
+    }
+```
+### Executing search, sort, filter and pagination operations 
+- When you need to perform these actions, you can append the query parameters to the GET method and the API endpoint. For example, to carry out a **search** operation for a particular pet:
+    - GET /pets?search=Blaze (This will search for a pet named Blaze)
+- **Pagination** helps you to manage the amount of resources you return and it is advisable to use the parameters offset and limit as shown in the example below:
+    - GET /pets?offset=10&limit=20 (Return pets between 10 to 20)
+- To **sort** the list of resources we can use multiple sort parameters in the query string. For example:
+     - GET /pets?sort=age_desc (Would sort the age in descending order.)
+- For **filtering** we can use one or more parameters in the query string. For example: 
+    - GET /pets?type=canine&age=7 
+
+<!-- theme: info -->
+>If too many query parameters are used in GET methods and the URL becomes too long, the server may return a ‘414 URL too long’ HTTP status. Parameters might be passed to the request body of a POST request as a solution to this challenge.
+
+### Versioning 
+It is good practice to version an API to describe the available features and resources it exposes. When this is properly done, the application consuming the API can submit explicit requests to a specific version of a feature or resource. For example, you can specify the version of the resource by means of a parameter within the query string affixed to the HTTP request: http://api.yourdomain.com/v2/pets/10/
+
+    
 

articles/modeling/openapi-validation.md

@@ -0,0 +1,14 @@
+# OpenAPI Validation
+
+![](../../assets/gifs/file-validation-oas-spec.gif)
+
+OpenAPI validation is the process of verifying the underlying OpenAPI file syntax by making sure it conforms to the [OpenAPI Specification requirements](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification) provided by the [OpenAPI Initiative](https://www.openapis.org/). Stoplight immediately validates any changes done to a spec to ensure they are in the correct format prior to being saved.
+
+<!-- theme: info -->
+> Stoplight currently supports the OpenAPI v2 specification. We are working on support for OpenAPI v3, and should have more information in the coming months.
+
+***
+
+**Related**
+
+* [File Validation](../editor/file-validation.md)

articles/modeling/security-schemes.md

@@ -1 +1,54 @@
+# API Security Schemes
+API security schemes protect your API resources by authenticating apps or users that consume your API. There are a number of standard authentication protocols you can pick from and each has their own strengths and weaknesses. To help you get started, the section below outlines some common schemes in use.
+
+## Authentication Schemes
+### Basic API Authentication
+- Easy to implement
+- Entails sending encoded username and password details
+- Usually bundled with standard framework or language library
+- Used with HTTPS, TLS or SSL
+- Can be combined with other security methods
+- **Note**: this method is susceptible to hijacks and man-in-the-middle attacks
+
+### OAuth1.0 (Digest Scheme)
+- Popular, tested, secure, signature driven, protocol
+- Uses cryptographic signature, which is a mix of token secret, nonce, and other request based information.
+- Can be used with or without SSL
+
+### OAuth2 (Bearer Token Scheme)
+- The current OAuth2 specification eliminates need for cryptographic signatures, passwords, and usernames.
+- OAuth2 works with authentication scenarios called flows, these flows include:
+    - Authorization Code flow
+    - Implicit flow
+    - Resource Owner Password flow
+    - Client Credentials flow
+- The OAuth 2.0 server will distribute access tokens that a client application will use to access protected resources.
+- [Additional Information on OAuth2.0](https://tools.ietf.org/html/rfc6749)
+
+### OpenID Connect Discovery
+- OpenID Connect Discovery (OIDC) is based on the OAuth 2.0 protocol.
+- Uses a sign-in flow that permits user authentication and information access by a client app.
+- The user information is encoded via a secure JSON Web Token (JWT). 
+- [Additional Information on OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) 
+
+## Best Practices 
+### Implementing IDs
+Unique User IDs should be distinctive but not easy to decipher. 
+- Example: using ‘a12bc3’ is weak when compared to an ID that reads ‘09dgf659sjf038eyr3367dhrt34j5’. Avoid using auto increment for your Unique User IDs to reduce the likelihood of a security breach. 
+### Sensitive Information in HTTP Request 
+Ensure that your API will not expose important information such as password, API keys, and security tokens in the URL. For example, this URL is bad because it contains an API key: 
+- /baseurl/<uid>q=?apiKey=2123223223 
+### API Keys 
+Reduce the likelihood of exposing your API keys by keeping them in a file or storage mechanism that is accessible by the owner. 
+- **Note**: API Keys can be duplicated or lost so it is important to use other security measures apart from API keys. Consider encryption to make your API keys more secure. 
+  
+### Validation 
+It is beneficial to validate your inputs and access to resources using robust parsers. Parsing requests can help verify the validity of user requests. API designers can perform an implicit input validation to ensure the user inputs data with permitted characters, right syntax and character length. Using regular expressions can also help validate string inputs. If a request exceeds the defined limit, you can return a ‘413 Request Entity Too Large’ response code. 
+
+### Audit log 
+Create audit logs before and after security related events. You can also log validation errors to detect patterns or potential attacks.
+### HTTP Status Codes 
+Use status codes and proper error handling techniques for incoming requests to identify probable security risks.
+- [Additional Information on HTTP Status and Error Codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
+
 

articles/organizations/create-org.md

@@ -1,17 +1,17 @@
 # Create An Organization 
 
-![](/assets/gifs/org-create.gif)
+![](../../assets/gifs/org-create.gif)
 
 ## What 
 * Organizations are great for grouping people, data, and billing together in one convenient location 
 
 ## Who 
-* Only the Billing **Owner** or Organization **Administrator** can create organizations 
+* Only the Billing **Owner** or Organization **Administrator** can create Organizations 
 
 ## How 
 1. Click on **+ New**  to the right of Organizations 
 2. Fill in **Name** 
-    * We recommend using your company’s name.
+    * We recommend using your company’s name
 3. Choose the path for your Organization (optional)    
 4. Add member by email (optional) 
     * Input email accounts to add other members to your organization 

articles/organizations/customize-org.md

@@ -1,17 +1,19 @@
 # Customize Your Organization 
 
-![](/assets/gifs/org-settings.gif)
+![](../../assets/gifs/org-settings.gif)
 
 ## What 
-* Want to modify your organization? In Stoplight you can modify your organizations: 
+* Want to modify your Organization? In Stoplight you can modify your Organization's: 
     * Name 
     * Org Path 
     * Add a Description 
     * Add an Org Image 
+    
 ## Who 
 * Only an Organization **Owner** or **Administrator** can modify Organizations  
+
 ## How
-1. From the homepage select the **Organization** you would like to modify 
+1. From the homepage, select the **Organization** you would like to modify 
 2. Select the **Settings** tab 
 3. Input a **Name** 
 4. Input a **Path** 

articles/organizations/delete-org.md

@@ -1,13 +1,13 @@
 # Delete an Organization 
 
-![](/assets/gifs/org-settings.gif)
+![](../../assets/gifs/org-settings.gif)
 
 ## What 
 * Deleting an organization is easy peasy, but once you delete an Org, there is no going back. Please be certain. 
 ## Who 
 * Only the Organization’s **Owner** 
 ## How
-1. From the homepage select the **Organization** you would like to delete 
+1. From the homepage, select the **Organization** you would like to delete 
 2. Select the **Settings** tab 
 3. Scroll to the bottom of the page to the **Danger Zone**
 4. Click on **Delete this Org**

articles/organizations/managing-people.md

@@ -1,17 +1,17 @@
 # Invite People to an Organization
 
-![](/assets/gifs/people-invite.gif)
+![](../../assets/gifs/people-invite.gif)
 
 ## What 
-* Adding people to your organization is the first step towards collaborating in Stoplight
+* Adding people to your Organization is the first step towards collaboration within Stoplight
 
 ## Who 
-* Only an Organization **Owner** or **Administrator** can invite people to an organization 
+* Only an Organization **Owner** or **Administrator** can invite people to an Organization 
 
 ## How
-1. From the Stoplight homepage select the **Organization** you would like to invite people to 
-2. Select the **People** tab from the navigation bar 
+1. From the Stoplight homepage, select the **Organization** you would like to invite people to 
+2. Select the **People** tab from the tabs bar 
 3. Click **Invite Member** 
 4. In the popup that appears input email addresses or usernames 
 5. Hit **enter** to add them to your list 
-6. Once you have completed your list of members you wish to invite click the **Invite** button 
+6. Once completed, click the **Invite** button 

articles/organizations/remove-people.md

@@ -1,6 +1,6 @@
 # Remove People From Your Organization 
 
-![](/assets/gifs/org-member-remove.gif)
+![](../../assets/gifs/org-member-remove.gif)
 
 ## What 
 * Removing a person for your organization is as easy as 123...4...5...6
@@ -9,9 +9,9 @@
 * Only an Organization **Owner** or  **Administrator** can modify
 
 ## How 
-1. From the homepage select the **Organization** you would like to modify 
+1. From the homepage, select the **Organization** you would like to modify 
 2. Select the **People** tab from the tab bar 
 3. Find the person you would like to remove from the list 
-4. To the right of the person’s name click on the **dropdown arrow** to the left of the person’s role 
-5. In the dropdown menu that appears select **Remove Member** 
+4. To the right of the person’s name, click on the **dropdown arrow** to the left of the person’s role 
+5. In the dropdown menu that appears, select **Remove Member** 
 6. Click **Okay** in the popup prompt 

articles/organizations/roles.md

@@ -4,20 +4,19 @@
 
 ## What 
 * Roles and Permissions for members of Organizations can be managed and modified within Stoplight to control access to the Organization's functions and features 
-    * There are 4 Roles: 
+    * There are 3 Roles: 
         * **Owner** 
-            * Owners can update the org, its connections, and its collaborators 
-            * Access to Billing and Organization Settings 
-            * There can only be one owner of an org 
+            * Owners can update the org, its connections, and its members 
+            * Has access to Billing and Organization Settings
         * **Administrator** 
-            * Admins can update the org, its connections, and its collaborators. 
+            * Admins can update the org, its connections, and its members 
         * **Member** 
-            * Members can update the org and its connections. They can view its collaborators. 
+            * Members can update the org and its connections. They can view its members 
 
 ## Who
 * Only an Organization **Owner** or **Administrator** can modify roles and permissions 
 ## How 
-1. From the homepage select the **Organization** you would like to modify 
+1. From the homepage, select the **Organization** you would like to modify 
 2. Select the **People** tab from the tab bar 
 3. Find the person you would like modify 
 4. To the right of their name click on the **down carrot** button to the left of the person’s role 

articles/organizations/transferring-ownership.md

@@ -3,7 +3,7 @@
 ![](/assets/gifs/org-transfer.gif)
  
 ## What 
-* You can promote another Member of your Organization to the role of Owner. 
+* You can promote another Member of your Organization to the role of Owner
     * You can only transfer ownership to a Member of the Organization
 ## Who 
 * Only the Organization **Owner** can transfer ownership of an Organization 
@@ -11,7 +11,7 @@
 1. From the homepage select the **Organization** you wish to modify 
 2. Select **People** from the tabs bar 
 3. Find the Member you would like to modify from the list 
-4. To the right of the Member’s name click on the **down carrot** next to the Member’s current role 
-5. From the dropdown menu that expands select **Owner** 
+4. To the right of the Member’s name, click on the **down carrot** next to the Member’s current role 
+5. From the dropdown menu that expands, select **Owner** 
 6. You will then be asked to confirm your selection in a popup window
 7. Click **Ok** 

articles/prism/validation.md

@@ -0,0 +1,4 @@
+
+<!--stackedit_data:
+eyJoaXN0b3J5IjpbLTE5Mzc0MDU2MjJdfQ==
+-->

articles/projects/change-member-role.md

@@ -17,7 +17,7 @@
       
    
 ## 	 Who 
-* Only Organization **Owner** and Org and/or Project **Administrators** have invite privileges 
+* Only the Organization **Owner** and Org and/or Project **Administrators** can modify member roles
 
 ## How
 1. From the Stoplight homepage select the **Project** you wish to modify 

articles/projects/create-project.md

@@ -1,6 +1,6 @@
 # Creating a Project  
 
-![](/assets/gifs/project-create.gif)
+![](../../assets/gifs/project-create-personal.gif)
 
 ## What 
 Projects are the workspace of the Stoplight Platform. Projects contain: 

articles/projects/invite-people-team.md

@@ -1,6 +1,6 @@
 # Invite People & Teams to a Project
 
-![](/assets/gifs/project-member-invite.gif)
+![](../../assets/gifs/project-member-invite.gif)
  
 ## What 
 * You can invite people to a Project to grant them read or read/write permissions 
@@ -15,12 +15,13 @@
     * **Read Access**: Low-level permissions that allow you to: 
         * Read
       
+<callout>You can only invite people and Teams to a Project associated with an Organization</>
    
 ## 	 Who 
-* Only Organization **Owner** and Org and/or Project **Administrators** have invite privileges 
+* Only the Organization **Owner** and Org and/or Project **Administrators** have invite privileges 
 
 ## How
-1. From the Stoplight homepage select the **Project** you wish to modify 
+1. From your Organization's homepage, select the **Project** you wish to modify 
 2. By deafult, all members of the Organization the Project is associated with will have Read permission 
 3. To invite a single member, select the **Member icon** from the far left sidebar
     * Input their username in the search bar at the top of the Member sidebar

articles/projects/visibility.md

@@ -1,6 +1,6 @@
-## Making Your Project Private/Public
+## Making Your Project Private & Public
 
-![](/assets/gifs/project-privacy.gif)
+![](../../assets/gifs/project-privacy.gif)
 
 ## What 
 * You can choose to make your Project Public or Private 

articles/teams/add-people.md

@@ -1,16 +1,21 @@
 # Add People to a Team 
 
-![](/assets/gifs/team-member-remove.gif)
+![](../../assets/gifs/team-member-remove.gif)
 
 ## What 
+
 * Adding people to a team lets you collaborate on projects while allowing an additional level of control over permissions.
+
 ## Who 
+
 * Team **Owners**, **Administrators**, and **Members** can add people to a team 
+
 ## How
+
 1. From the homepage select the **Organization** associated with the team 
 2. Select **Teams** on the tab bar
 3. Select the team that you would like to add people to.
 4. Click the **Invite Members** button
 5. Input the person’s email or Stoplight username in the textarea and press enter 
     * Note: you can add more than one person at a time
-6. Once completed click on the **Invite** button
+6. Once completed, click on the **Invite** button

articles/teams/create-team.md

@@ -1,14 +1,15 @@
 # Create a Team 
 
-![](/assets/gifs/team-create.gif)
+![](../../assets/gifs/team-create.gif)
 
 ## What 
 * Teams makes it easier for Organization Members to collaborate and allows additional control over permissions 
 
 ## Who
-* Only an Organization **Owner** or **Administrator** can create Teams
+* Only an Organization **Owner** or **Administrator** can create a Team
+
 ## How
-1. From the homepage select the **Organization** you would like to make a team for 
+1. From the homepage, select the **Organization** you would like to make a team for 
 2. Select the **Teams** tab from the tabs bar 
 3. Create Your First Team 
     * Input a **Team Name**(A department, project group, etc.)  

articles/teams/customize-team.md

@@ -1,12 +1,17 @@
 # Customize a Team 
 
-![](/assets/gifs/teamcustom.gif)
+![](../../assets/gifs/teamcustom.gif)
 
 ## What 
+
 * You can customize the Team Name, Path, and Team Description 
+
 ## Who 
+
 * Only Team **Owner** or **Administrator** can customize a Team
+
 ## How
+
 1. From the homepage select the **Organization** associated with the Team you wish to modify 
 2. Select **Teams** from the tab bar 
 3. From the Teams homepage select the Team you wish to customize

articles/teams/delete-team.md

@@ -1,14 +1,14 @@
 # Delete a Team 
 
-![](/assets/gifs/teamcustom.gif)
+![](../../assets/gifs/teamcustom.gif)
 
 ## What 
 * Want to disband your team? Here's how: 
 ## Who 
-* Only Team **Owner** or **Administrator** can delete a team 
+* Only the Organization **Owner** or a Team **Owner** or **Administrator** can delete a team 
 ## How 
 1. Select the **Organization** associated with the team you wish to modify 
 2. Select **Teams** from the tab bar 
-3. Click on the **red x icon** located to the right of the team you wish to delete 
+3. Click on the **red X icon** located to the right of the team you wish to delete 
 4. A popup will appear asking if you are sure you want to delete this team 
 5. Click **Ok** 

articles/teams/member-roles.md

@@ -4,19 +4,19 @@
 
  ## What 
 * Roles and Permissions for Team members can be managed and modified within Stoplight to control access to the Team’s functions and features 
-    * There are 4 Roles: 
+    * There are 3 Roles: 
         * **Owner** 
-            * Owners can update the Team, its connections, and its collaborators. Can update/delete this team's settings. There can only be one owner of an org 
+            * Owners can update the Team, its connections, and its collaborators. They can also update the team's settings and delete the team.
         * **Administrator** 
             * Admins can update the Team, its connections, and its collaborators. 
         * **Member** 
-            * Members can view and create projects. They can view its members
+            * Members can view and create projects. They can view the Team's members.
            
 ## Who
-* Only Team **Owner** or **Administrator** can modify Roles and Permissions 
+* Only the Team **Owner** or **Administrator** can modify Roles and Permissions 
 
 ## How 
-1. From the homepage select the **Organization** associated with the Team you would like to modify 
+1. From the homepage, select the **Organization** associated with the Team you would like to modify 
 2. Select the **Teams** tab from the tab bar 
 3. Select the Team you would like modify 
 4. To the right of the member’s name click on the **down carrot** button to the left of the person’s role 

articles/teams/remove-people.md

@@ -1,14 +1,19 @@
 # Remove People from a Team
 
-![](/assets/gifs/team-member-remove.gif)
+![](../../assets/gifs/team-member-remove.gif)
  
 ## What 
+
 * Want to bench a member of your team? Here's how: 
+
 ## Who 
-* Only Team **Owner** or **Administrator** can remove people from a Team 
+
+* Only the Team **Owner** or **Administrator** can remove people from a Team 
+
 ## How 
+
 1. From the homepage select the **Organization** associated with the Team you wish to modify
-2. Select **Team** from the tab bar 
+2. Select **Teams** from the tab bar 
 3. Select the Team you wish to modify from the list 
 4. Find the member of the team you wish to remove 
 5. To the right the member’s name click the **down carrot** 

articles/teams/transfer-ownership.md

@@ -1,6 +1,6 @@
 # Transfer Primary Ownership of a Team 
 
-![](/assets/gifs/team-transfer.md)
+![](../../assets/gifs/team-transfer.gif)
 
 ## What 
 * You can transfer Ownership of a Team to another member of the Team 

articles/testing/variables-context.md

@@ -0,0 +1 @@
+

articles/testing/variables-environment.md

@@ -0,0 +1 @@
+

articles/testing/variables-overview.md

@@ -0,0 +1 @@
+

validation.md

@@ -0,0 +1,4 @@
+
+<!--stackedit_data:
+eyJoaXN0b3J5IjpbLTE5Mzc0MDU2MjJdfQ==
+-->