<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Stoplight on Medium]]></title>
        <description><![CDATA[Stories by Stoplight on Medium]]></description>
        <link>https://medium.com/@stoplightio?source=rss-4b40032f3cfc------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*gCXhF_zepdW1TR7b.png</url>
            <title>Stories by Stoplight on Medium</title>
            <link>https://medium.com/@stoplightio?source=rss-4b40032f3cfc------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 07:45:22 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@stoplightio/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Scenarios v3.4 Release]]></title>
            <link>https://medium.com/api-corner/scenarios-v3-4-release-2eff3345918?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/2eff3345918</guid>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Mon, 31 Jul 2017 14:11:59 GMT</pubDate>
            <atom:updated>2017-07-31T15:15:00.312Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QWJdJM991LtZJ43qgUDLsg.png" /><figcaption>The new tagging system helps your team keep things organized.</figcaption></figure><p>Today, we are happy to announce the release of Scenarios v3.4! This release includes several highly requested features, as well as a slew of bug fixes. You can check all of this out now at <a href="https://scenarios.stoplight.io/">https://scenarios.stoplight.io</a>.</p><h4>v3.4 highlights:</h4><ol><li>Tagging &amp; Filtering</li><li>Discussions</li><li>Shared Environments</li><li>Public Entities</li><li>Editor UI Update</li></ol><p><strong><em>Notes</em></strong><em>: This release requires you to re-login. This release clears private environment variables due to the new shared environments system — we apologize for the inconvenience!</em></p><h3>Tagging &amp; Filtering</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uGL3lxZulxt8hIKDI6jFuQ.png" /><figcaption>Manage tags on your organization settings page.</figcaption></figure><p>Tags help you organize the many artifacts that are part of your development process. You can define tags in your organization, and then add them to entities (API specs, scenario collections, and prism instances) inside of the organization.</p><p>Use tags to organize your lifecycle stages (design, needs review, published, etc), group entities into projects, deprecate entities, and more.</p><p>Every organization starts off with some basic tags, but they are fully customizable on the settings page.</p><p><strong><em>Coming Soon: </em></strong><em>A kickass search system.</em></p><h3>Discussions</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*T5Jzo_KtjS6x-yAgYdWt6w.png" /><figcaption>Discussions make it easy for stakeholders to coordinate.</figcaption></figure><p>Every editor now has a discussions pane, accessible via a button in the top right.</p><p>Discussions make it easy for stakeholders to coordinate. Use discussions to ask questions, assign tasks, and resolve issues.</p><p>To create a new discussion, simply navigate to the entity in question, and then click on the “Discussion” button in the top right. Anybody with read access to the entity can create and participate in discussions. Discussions can be resolved, and you can toggle between open and closed discussions with the tabs at the bottom of the discussion list.</p><p><strong><em>Coming Soon: </em></strong><em>@mentions, activity feeds, and notifications!</em></p><h3>Shared Environments</h3><p>Environments make it easy to define groups of variables that you can re-use throughout your API spec / scenario collection /etc.</p><p>Before v3.4, each entity was limited to 3 pre-defined environments (development, staging, and production). Additionally, environment data was always specific to each user, and only saved on their computer.</p><p>v3.4 introduces the concept of shared environments. You still have the three pre-defined default environments, but now you can also add your own. You can also save shared variables to environments. These variables are usable by anybody with read access to the entity. Shared variables are great for properties that are applicable to more than one person (like API hosts).</p><p>Don’t worry — private user variables are still supported! Private environment variables are only saved on the individual users computer (not Stoplight servers), and are merged over any shared variables of the same name. This lets individual users customize shared variables when needed, without affecting their teammates.</p><h3>Public Entities</h3><p>Entities can now be made public! This makes it easier to share API Specs and other development artifacts with people outside of your organization.</p><p><strong><em>Coming Soon: </em></strong><em>Pretty, read-only/documentation views for all of our editors. These will be perfect to share with the public and/or less technical stakeholders in your organization.</em></p><h3>Editor UI Update</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7aGeACeAj1xr_i8wwZV9CA.png" /></figure><p>We’ve updated the editor UI in a few small ways. The primary goal here was to increase the amount of space available to the editor itself by minimizing the navigational chrome around it. To do that, we’ve moved the tabs that used to be at the top of the editor to a new left gutter. This significantly increases the amount of vertical space available to the editor. This also allowed us to increase the height of the top nav strip, which is important because…</p><p><strong><em>Coming Soon: </em></strong><em>Multiple tabs support. No clicking through lots of links to switch back and forth between two things in the app.</em></p><p>We hope you enjoy this release! Please let us know if you run into any bugs, or have questions.</p><p>We’re on Twitter <a href="http://twitter.com/stoplightio">@stoplightio</a> and available by email at hi [at] stoplight.io.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2eff3345918" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/scenarios-v3-4-release-2eff3345918">Scenarios v3.4 Release</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Using API Mocking to Unblock Teams]]></title>
            <link>https://medium.com/api-corner/using-service-virtualization-api-mocking-to-unblock-teams-2914843cf56e?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/2914843cf56e</guid>
            <category><![CDATA[api-development]]></category>
            <category><![CDATA[api-design]]></category>
            <category><![CDATA[mocking]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Tue, 20 Jun 2017 20:54:56 GMT</pubDate>
            <atom:updated>2018-10-10T16:05:25.987Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KdYoj5pmvmF2bKvtRk6IIQ.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/photos/BboZKgHg0Yw?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Nathan Gonthier</a> on <a href="https://unsplash.com/?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>There’s no denying that a well-written test suite breeds a better product. Not only does it provide a high level of confidence in your code, but it also covers your butt whenever you make any changes.</p><p>And an essential part of a well-written test suite is mocking. Mocking helps keep individual tests focused and lightweight, which ensures a fast, clean test suite, and provides a mechanism for testing functionality that requires objects that aren’t quite finished yet.</p><p>Here are a few ways mocking can help you overcome the most common problems you face when delivering software.</p><h4>Service Virtualization</h4><p>Although mocking is often used in the context of unit testing, a far more powerful use case for it is service virtualization. In a nutshell, a virtualized service is a mock API. Following the definition above, a mock API simulates the behavior of a real API.</p><p>While mock APIs can be used for unit testing, a more common use case is the parallelization of work. By standing up a mock API server, teams that are building features that are dependent on that API can begin working on them without waiting for the API to actually exist. This ensures that, API or no, each team can work as productively as possible.</p><p>Beyond simply allowing teams to work better in tandem, how does service virtualization help teams build a <em>better</em> product together?</p><h4>Emphasize Form and Function</h4><p>In my experience, teams that communicate well perform well. Standing up a mock API server is an important step towards unblocking conflicting team priorities, but that is only half of the battle. The other half is the actual design of the mock API.</p><p>In the early stages of product design, when the design and usability of a product are being worked on, and the architecture is being decided, outlining the form and function of the API is a crucial step. Much like how writing API documentation <em>before</em> developing an API helps identify usability and design problems, designing a mock API with all stakeholders present can provide the same benefit.</p><p>Once the design of the API has been agreed upon, any teams dependent on it can begin working in tandem on their own piece of the product puzzle. This mock API not only works to unblock the various stakeholders — it also acts as a blueprint for the API development team to follow. Defining the expected endpoints, requests, and responses early on will drastically speed up API development. When the decisions are already made, no time is wasted.</p><h4><strong>Research and Development</strong></h4><p>The beauty of mock API servers is that spinning one up can be a relatively trivial task through the use of third-party platforms like Stoplight.io. These platforms make testing out new API ideas fast and easy, while also providing the ability to use proxies to turn these ideas into something more substantial if they take hold. For example, these servers can be used to further the goals of an organization with minimal engineering intervention by establishing a feedback loop on a beta version of an existing API.</p><p>By spinning up a mock server using something like Stoplight.io, an organization can work directly with early adopters to design an API that best fits their needs. High-value customers receive the opportunity to update their integrations to the next version of an API while it is still being designed, allowing you to write and rewrite the API specifications without having to change any code. This high-touch feedback loop can go a long way towards building a healthy relationship with valuable customers, while also keeping the workload of the engineering team at a manageable level.</p><h4>Taking It Further</h4><p>One way to take a mock API further than simply filling in some blanks is to use it to validate the completeness of the official API development. By comparing the API with the mock API, we can determine which endpoints are done, which ones aren’t, and which ones do not match the design spec. This is a great way to close the loop on product development, as once the API and mock API are in parity, the mock API can then be integrated directly into the test suite to ensure that the API <em>stays</em> accurate.</p><p>In the end, service virtualization should make your organization more efficient, not less, so it is important to focus on the things that matter. API design, communication, documentation, consistency, and test integrations are all huge gains that can be the difference between a two-month project and a 10-month project.</p><p><em>Have an API, want to add mocking into the mix? </em><a href="http://scenarios.stoplight.io/"><em>Stoplight Scenarios</em></a><em> makes it easy to mock both pre-existing APIs, and new APIs.</em></p><p><strong><em>About the author:</em></strong><em> Zachary Flower (</em><a href="http://twitter.com/zachflower"><em>@zachflower</em></a><em>) is a freelance web developer, writer, and polymath. He has an eye for simplicity and usability, and strives to build products with both the end user and business goals in mind.</em></p><p><em>Want to write for Stoplight? We’re hiring! Shoot an email to hi@stoplight.io and let’s chat.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2914843cf56e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/using-service-virtualization-api-mocking-to-unblock-teams-2914843cf56e">Using API Mocking to Unblock Teams</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Scenarios v3.3 Update]]></title>
            <link>https://medium.com/api-corner/scenarios-v3-3-update-e2e7f7b39603?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/e2e7f7b39603</guid>
            <category><![CDATA[development]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[developer-tools]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Mon, 12 Jun 2017 20:35:56 GMT</pubDate>
            <atom:updated>2017-06-12T20:43:48.973Z</atom:updated>
            <content:encoded><![CDATA[<p>Last Thursday we released one of the biggest updates to Scenarios yet. It includes numerous bug fixes, a whole lot of polish, and several new features. This release also coincides with Prism v2-alpha.5, which includes a couple of breaking changes - described below.</p><h3>Platform Updates</h3><h4>Modeler Polish</h4><p>Our OAS/Swagger 2 modeling tool received a big update. Not only did we squash all of the bugs reported over the last month, but we’ve added shortcuts and organizational improvements throughout the editor.</p><ul><li>You can more quickly extend your specification with buttons in the sidebar.</li><li>Operation data is organized into collapsible sections.</li><li>Most of the root properties have been consolidated to one organized home screen (like consumes, produces, info, etc).</li><li>We now support the global security property in the UI.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/596/1*raBK-gZJrKBBie5wp8yV-g.gif" /><figcaption>New context-aware actions in the sidebar to quickly add to your spec.</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xxGweKczpkW4wCGwc5VpiA.gif" /><figcaption>Switch between UI and “raw” edit modes. Navigate the sidebar and the relevant parts of your spec will highlight.</figcaption></figure><h4>Share Model Data With Connections</h4><p>As the number of APIs under management increases, it is often desirable to extract common pieces out into a shared API specification(s). These shared pieces can include common model definitions, operations, responses, parameters, and security definitions.</p><p>Scenarios v3.3 takes a first step towards this type of functionality. You can now connect API Specs to other API Specs, and then reference models and responses defined in the connected spec. This is all built around the OAS and JSON Schema standards — there is nothing proprietary about it, and your resulting API specs will work well with any tooling that supports these standards.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fi.imgur.com%2Fe4MRjGy.mp4&amp;src_secure=1&amp;url=https%3A%2F%2Fi.imgur.com%2Fe4MRjGy.gifv&amp;image=https%3A%2F%2Fi.imgur.com%2Fe4MRjGyh.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=video%2Fmp4&amp;schema=imgur" width="1376" height="748" frameborder="0" scrolling="no"><a href="https://medium.com/media/70b76704849d4e58da19636acec35be5/href">https://medium.com/media/70b76704849d4e58da19636acec35be5/href</a></iframe><h4>HTTP Try It Out</h4><p>Sending requests to debug your API can be very useful. Typically, you would either do this with cURL, or by defining the requests in client like Postman. Now, with Stoplight, you can use your existing API specification to quickly send requests to your APIs — no need to define and maintain another set of data to send requests (Postman), or manually put together cURL requests.</p><p>To use the new feature, simply navigate to your API spec, and then select the “HTTP Try It Out” tab at the bottom of the editor. The request maker tool will autocomplete according to your spec, and update as you navigate around the API operations listed in the sidebar.</p><p>Additionally, Stoplight will contract test your existing specification against the request sent. This immediately tells you if your response schemas are accurate to your API (see the “Tests” tab in the gif below).</p><p>Finally, you can send requests and then click the magic wand icon at the top of the editor to extend your specification, using the data in the HTTP request. This is a great way to quickly create hundreds of lines of OAS code for pre-existing APIs.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fi.imgur.com%2Frrs9nRt.mp4&amp;src_secure=1&amp;url=https%3A%2F%2Fi.imgur.com%2Frrs9nRt.gifv&amp;image=https%3A%2F%2Fi.imgur.com%2Frrs9nRth.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=video%2Fmp4&amp;schema=imgur" width="1376" height="746" frameborder="0" scrolling="no"><a href="https://medium.com/media/2ebfeb79907c19afbfc711ddf0ec59d8/href">https://medium.com/media/2ebfeb79907c19afbfc711ddf0ec59d8/href</a></iframe><h3>Prism Updates</h3><p>The Scenarios collection format received a small update. Collections stored on Stoplight’s servers have been automatically migrated. If you are using the local file feature, you should see a “Migrate” button in the top left of the scenarios editor. Clicking that will migrate your local file to the latest format, and explain the changes.</p><p>We anticipate that this will be one of the final changes to the collection format (if not the final one) before the formal Prism 2 release.</p><h4>CLI Breaking Changes</h4><p>If you are using the Prism 2 alpha to work with Scenarios, run “prism update” in your terminal to get the latest version, which is 2-alpha.5 at the time of this writing. Run “prism version” to see what version you currently have installed. More details on the changes <a href="https://github.com/stoplightio/prism/releases/tag/v2.0.0-alpha.4">here</a>.</p><p>Over the next month we will be introducing easier one-click mock servers, and Hubs! Hubs is the next version of our documentation platform, and we are are excited to share what we have been working on with everybody. If you have not already, you can sign up for scenarios at <a href="https://scenarios.stoplight.io/">https://scenarios.stoplight.io</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e2e7f7b39603" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/scenarios-v3-3-update-e2e7f7b39603">Scenarios v3.3 Update</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[API Testing: Achieving Quick and Easy Service Virtualization with Stoplight]]></title>
            <link>https://medium.com/api-corner/api-testing-achieving-quick-and-easy-service-virtualization-with-stoplight-a590f20a414f?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/a590f20a414f</guid>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Wed, 31 May 2017 16:42:58 GMT</pubDate>
            <atom:updated>2017-07-13T15:37:59.664Z</atom:updated>
            <content:encoded><![CDATA[<p>API testing is being adopted at an increasingly faster rate. This may be partly due to the wide adoption of RESTful services over the years, which are prized for their ability to match the quick iteration of dev teams.</p><p>Yet while API testing is increasingly common, it’s not necessarily a fun thing to do. For many DevOps teams, API testing is a time-consuming and difficult process. The act of writing API tests can be tedious; it sucks the joy out of being a developer. Sometimes, testing is left to QA, isolating developers from the process — which is never good, because according to the DevOps mantra, no one should work in silos.</p><p>Fortunately, there’s a way to make API testing fun and easy again. It involves using service virtualization to take the tedium out of the traditional testing workflow.</p><p>In this article, I’ll show you how API testing can add significant value to your team, and how easy it is to implement with Stoplight. I’ll start by walking you through setting up an API spec for a basic CRUD service. Then we’ll run some tests.</p><h4><strong>Something to Test</strong></h4><p>For the purposes of this article, we’ll assume we have a simple <em>Express</em> and <em>Node.js</em> API that performs some basic CRUD operations on a MongoDB database. Each document has a schema matching the following example:</p><pre>{<br> &quot;_id&quot;: &quot;5889481213d6a93ada33e23c&quot;,<br> &quot;item&quot;: &quot;Canned tomato soup&quot;,<br> &quot;quantity&quot;: 7,<br> &quot;expires&quot;: &quot;2018–04–13&quot;,<br> &quot;created&quot;: 1492916510<br>}</pre><h4><strong>Connecting the Services to Stoplight</strong></h4><p>The next step is to set up an account for testing. If you don’t already have a Stoplight account, head over to their website and get their new desktop app, <a href="http://stoplight.io/platform/scenarios/">Scenarios</a>. Sign up and create a new organization.</p><p>Next, create an API specification. Make sure the <strong>API Spec </strong>tab is selected and fill out the form. All we need for this example is a name.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/977/0*cvftwMv_Scx1ag73." /></figure><p>Now that you are in, you can use Stoplight’s visual CRUD builder to define your model. All changes made via the interface write to the Swagger spec, displayed in the built-in text editor to the bottom of your window.</p><p>Stoplight’s Visual OpenAPI Specification (OAS) Editor is intuitive and easy to navigate. However, to save time, I copied the contents of this Swagger file: <a href="http://www.jsoneditoronline.org/?id=ed42666d21301233f5d9a99a53d06f9c">http://www.jsoneditoronline.org/?id=ed42666d21301233f5d9a99a53d06f9c</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*N2pvMEAdZdVU9sor." /></figure><p>I want to take a minute to talk about the OpenAPI Specification. If you are unfamiliar with OAS, check it out over at <a href="https://github.com/OAI/OpenAPI-Specification">https://github.com/OAI/OpenAPI-Specification</a>.</p><p>Although knowledge of OAS is not required to use Stoplight, learning it puts you in a better position to dramatically improve the way you and your team work with and on REST APIs. It was designed to add a layer of abstraction over an API, so that computers and humans are able to instantly understand the functions of the API without reviewing source code or reading documentation. I highly recommend giving it the time.</p><p>Stoplight in its purest form is an OpenAPI editor. All edits made in the visual editor can be written either to Stoplight servers or to a JSON file on your local machine to an editable Swagger JSON file.</p><h4>API Testing</h4><p>At this point, we now have our API specification. Hooray!</p><p>The next thing we need is to be sure that our API works and that it reflects what we described in our API spec. We can do this quite easily by heading over to the Scenarios section of the Stoplight app.</p><p>Click your organization’s name in the breadcrumbs navigation in the top left. Then create a new <strong>Scenarios Collection. </strong>Give your collection a name.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/845/0*FwgCF--OLbapskU_." /></figure><p>Once in, the first thing you need to do is connect your spec, the one we defined before, so go to the <strong>Connections </strong>tab and click <strong>Select Specs. </strong>Look for the spec you defined previously from the dropdown menu labelled <strong>SRN.</strong></p><p>Go back to <strong>Scenario Collection.</strong></p><p>Under the <strong>Collection Settings, </strong>set your API’s host. I’m running locally on port 3000.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/962/0*53BODTHr7yrpaZnW." /></figure><p>Next, on the <strong>Coverage</strong> tab, you’ll notice that Stoplight has read the contents of your spec and displayed all the operations and their endpoints.</p><p>From here, we can quickly click endpoints to create a scenario. Let’s run through an example scenario:</p><ol><li>POST a new item. Passes if the status code is 201 and the response object is valid.</li><li>GET the newly created item using the ID returned in the response object when the item was created. Passes if the status code is 200 and the response object is valid.</li><li>PUT to the same item using the ID returned in the response object. Passes if the status code is 200 and the response object is valid.</li><li>DELETE the same item using the ID returned in the response object. Passes if the status code is 204 and the response object is valid.</li><li>GET the same item using the ID returned in the response object — The object should no longer exist and return a 404 in order to pass.</li></ol><p>Now, we’re almost ready to run our test. We just need to double-check to make sure we capture the ID after the object is created.</p><p>From the sidebar, select <strong>CREATE item</strong>. Then from the <strong>Captures</strong> tab, choose <strong>Add Capture</strong>. Give your capture a name. I went with itemsId. Select from the output body output.body, and type the name of the property. In our case, we want _id.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*BeqGBYd1smQ8uRMD." /></figure><p>Perfect! We are all set to run our tests. Click <strong>Run Scenario </strong>and watch your tests pass.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*t8dBL7bgJ8aoabLW." /></figure><h4>In Conclusion</h4><p>There are a number of things about Stoplight’s Scenarios that we didn’t cover here. If you wish to get more insight into what else it can do, a good place to look is <a href="https://blog.stoplight.io/introducing-scenarios-3b88242cf9cc">Intro to Scenarios</a>. This is by no means a complete overview of Stoplight and its tools. My hope is, however, that if you have been on the fence about writing tests, or don’t necessarily like to write them, that this intro will give you the courage to take the leap. The added benefit of using Stoplight is getting familiar with Swagger/OAS. It acts as a gateway to using more sophisticated or commonly used tools.</p><p><em>Have an API, need to test it? </em><a href="https://scenarios.stoplight.io/"><em>Stoplight Scenarios</em></a><em> make it easy to thoroughly test your APIs, both during development, and as part of your continuous integration process.</em></p><blockquote><strong>About the author.</strong> <a href="https://medium.com/@urimaxima">Uri Maxima</a> is a witty and brilliant software engineer, passionate about automation, intelligent design and social impact.</blockquote><blockquote>Want to write for Stoplight? We’re hiring! Shoot an email to hi@stoplight.io and let’s chat.</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a590f20a414f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/api-testing-achieving-quick-and-easy-service-virtualization-with-stoplight-a590f20a414f">API Testing: Achieving Quick and Easy Service Virtualization with Stoplight</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Components of Killer API Docs]]></title>
            <link>https://medium.com/api-corner/components-of-killer-api-docs-ebbf41c13450?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/ebbf41c13450</guid>
            <category><![CDATA[development]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[api-development]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Thu, 11 May 2017 14:56:54 GMT</pubDate>
            <atom:updated>2017-05-11T14:56:54.766Z</atom:updated>
            <content:encoded><![CDATA[<p>Let’s face it — Writing documentation sucks, but <em>not</em> writing documentation sucks a <em>lot</em> more.</p><p>Trying to use an API without clear and accurate documentation is like trying to read a book without any punctuation — It can be done, but it wastes a <em>ton</em> of time. As a developer, there’s nothing more frustrating than having to reverse engineer a third-party API because the vendor decided to skimp on the documentation.</p><p>Unfortunately, in today’s API climate, it’s not enough to simply have accurate documentation. It has to be clean, detailed, and unambiguous. The first impression a developer gets of an API is its documentation, so creating good API documentation is as much an exercise in usability and marketing as documentation.</p><h3>Is It Good?</h3><p>“So,” you might be thinking, “what exactly <em>is</em> good documentation?”</p><p>At a high level, good documentation is organized, detailed, accurate, and unambiguous. While every API approaches documentation a little differently, the ones that put a high level of care into their documentation all tend to share these same concepts.</p><h3>Organized</h3><p>Organizing API documentation can be almost as tough as designing the hierarchy of the API. While the documentation can generally follow the design of the API itself, it is important to identify and highlight important topics that do not fit within that paradigm.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*WCSYf3o6p-OM6hWj." /></figure><p><em>Strava API Documentation</em></p><p>Take the<a href="https://strava.github.io/api/"> Strava API documentation</a>, for example. It is organized in a way that separates API endpoints (called “resources”) from other important API information like rate limiting and conventions. This ensures that developers can quickly and easily find information about both the API design, and information about the API as a whole.</p><h3>Accurate</h3><p>Have you ever turned on an unfamiliar faucet, only to find out that the hot and cold taps have been mislabeled? Accuracy is the single-most important feature of any documentation. Worse than no documentation at all is inaccurate documentation, which can be dangerous and costly. The API producer-consumer relationship is one of trust, and when the accuracy of your documentation can’t be trusted, neither can your API.</p><h3>Detailed</h3><p>In writing, it is often said that less is more. Why use a paragraph when a sentence will do? Unfortunately, this is <em>not</em> the case with API documentation. Nobody has ever complained that an API’s documentation is <em>too</em> detailed. As long as it is clear and properly organized, the more information you can provide about an endpoint, parameter, or expected response, the better.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*mjg-qm39Ru7svpjw." /></figure><p><em>Plaid API Documentation</em></p><p>The<a href="https://plaid.com/docs/api/"> Plaid API documentation</a> does an excellent job of providing detailed resource documentation. Every endpoint is clearly outlined and, more importantly, every possible parameter is defined in detail. Because of this level of detail, there is no question as to what each parameter does, whether it is optional or required, and what its expected format is.</p><h3>Unambiguous</h3><p>Every long story needs a tl;dr. No matter how detailed your documentation is, the best way to learn how to use a system is through examples. Clear and concise examples are important because they show an API in action. They take abstract documentation and ground it in reality. It is important to note that while detailed documentation is important, examples are best when generalized. They should be a good representation of a typical request and response, with the detailed parameter and endpoint descriptions providing more depth and context.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/624/0*b8hE97kFCRZ-rb3S." /></figure><p><em>Stripe API Documentation</em></p><p>When it comes to examples, the<a href="https://stripe.com/docs/api"> Stripe API documentation</a> is second to none. Live documentation is tough to do right, and often requires end-user configuration, which can make the documentation more frustrating than it is worth. On the flip side, sample requests are useful, but can be hard to relate to. Stripe tackles this problem by providing example requests and responses with dummy data, unless you are an existing API consumer. In that case, Stripe returns real data directly from their API. This provides an element of context that can help you more accurately understand each documented endpoint.</p><h3>Next Steps</h3><p>While all good documentation contains many of the elements shown above, when it comes down to it, the most important thing to remember is that documentation is a product in and of itself. Usability and design are just as important as information, as developers may find themselves living in your documentation for an extended period of time. Anything that improves that experience always reflects positively — both on you and your product.</p><p><em>Have an API, need docs? </em><a href="https://stoplight.io/"><em>Stoplight.io</em></a><em> offers a suite of tools that make it easy to create killer API docs.</em></p><blockquote><strong>About the author.</strong> Zachary Flower (<a href="http://twitter.com/zachflower">@zachflower</a>) is a freelance web developer, writer, and polymath. He has an eye for simplicity and usability, and strives to build products with both the end user and business goals in mind. From building projects for the NSA to creating features for companies like Name.com and Buffer, Zach has always taken a strong stand against needlessly reinventing the wheel, often advocating for the use of well established third-party and open source services and solutions to improve the efficiency and reliability of a development project.</blockquote><blockquote>Want to write for Stoplight? We’re hiring! Shoot an email to hi@stoplight.io and let’s chat.</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ebbf41c13450" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/components-of-killer-api-docs-ebbf41c13450">Components of Killer API Docs</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing Scenarios]]></title>
            <link>https://medium.com/api-corner/introducing-scenarios-3b88242cf9cc?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/3b88242cf9cc</guid>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Thu, 09 Feb 2017 00:22:20 GMT</pubDate>
            <atom:updated>2017-02-09T21:01:05.246Z</atom:updated>
            <content:encoded><![CDATA[<h4>The lean, mean, API testing machine.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vR95gkhRz7YpJVQJPSaCbA.png" /></figure><p><strong>Getting Started</strong></p><p>Stoplight Scenarios is a powerful (but accessible!) product that takes the pain out of API testing. Today, we are releasing it as a standalone product, available <a href="https://scenarios.stoplight.io/">on the web</a>, and as a <a href="https://download-next.stoplight.io/">desktop app</a>.</p><p>We generally recommend the desktop app when possible, because it can work with local servers, behind firewalls, and with local files.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*epCvIcr8745JoqRijKg82A.png" /><figcaption>API Specification Coverage Report</figcaption></figure><p><strong>OAS / Swagger Integration</strong></p><p>If you are modeling your API with Swagger 2 (whether with the v2 Stoplight app, or with another tool), Scenarios can leverage that specification to automatically build tests for you, provide coverage reports, and apply the specification to your API in the form of contract tests. This is THE best way to make sure that your API specification accurately reflects your API!</p><p><strong>Continuous Integration … err, Integration</strong></p><p>Running Scenarios outside of Stoplight, as part of your CI process, is trivial. Just install <a href="http://stoplight.io/platform/prism/">Prism</a> on your computer or CI server, and then run something like:</p><pre>prism conduct myOrg/scenarios/myScenarios</pre><p>Prism will run your scenarios locally, pretty-printing out the results as it goes.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vvPlg4fKJxPesqva0_EtSA.gif" /><figcaption>read/write to files on disk</figcaption></figure><p><strong>Local File Writing</strong></p><p>The desktop app makes it easy to read/write to files on disk. This allows you to include your specs and tests alongside your code, version them with git, and use your favorite tools to manage them.</p><p>Just drag a Swagger or Scenario file onto the app, or click the “read/write to disk” toggle if already in the editor.</p><h3>FAQs</h3><ul><li><strong>Does Scenarios costs money? </strong>Nope! The base scenarios product is free. We will be charging for teams support in the near future. If you are a current paying Stoplight customer, your teams plan will carry over.</li><li><strong>I have a Stoplight account, can I use it? </strong>Yup, just login to Scenarios with your existing credentials. If you use Github to login to Stoplight, you’ll need to go through the forgot password process to generate a password.</li><li><strong>Can I run tests as part of my CI process? </strong>Yes! See above.</li><li><strong>Can I collaborate with my team? </strong>Soon! As in this month soon.</li><li><strong>Can I store my specs/tests with my code?</strong> Yes! Use the desktop app, and toggle the read/write to file mode to on in the scenarios editor.</li><li><strong>Why is this a standalone app? </strong>Scenarios is built on our upcoming v3 architecture. This architecture is generally faster, and allows for really cool things like read/writing to local files on disk. More info in the looking forward section below.</li><li><strong>I’m modeling my API in the v2 Stoplight app, can I use it in Scenarios? </strong>Yes! Open the scenarios app and navigate to the “New API Spec” form. On that form, paste in the URL to your v2 Stoplight Swagger JSON export. After importing, there is a button on the editor to “Reload from source”, which allows quick refreshing of the spec from an external source (in this case, v2 Stoplight app).</li><li><strong>How does this compare to Postman? </strong>Postman is a better fit for simple HTTP requests (Scenarios is overkill for this). Stoplight Scenarios is generally more robust than Postman when it comes to creating actual tests. Things that Scenarios supports that Postman does not include referencing tests from other tests, JSON schema testing, Swagger contract testing, simpler request chaining, local file writing, coverage reports, direct spec editing, multi scenario running, and more.</li><li><strong>I have more questions? </strong>And we hopefully have answers! Shoot us an email at support@stoplight.io.</li></ul><h3>Testing v1</h3><p>The testing module of the Stoplight app will be removed on March 15th. You are free to continue using it from now until then, and we will provide an automatic migration to Scenarios on March 15th.</p><h3>Looking Forward</h3><p>Scenarios is actually the first product on our new v3 architecture. This architecture is much more robust, and allows for powerful features like local filesystem read/write for seamless interop with your existing workflows (whether it’s generating API specification from code, storing specs in Git, or using your favorite IDE to bulk edit specs every once and a while).</p><p><strong>There will be no changes to existing v2 users in the immediate future</strong>. We are developing v2 (app.stoplight.io) and v3 in tandem, and will be including next generation versions of v2 systems like mocking, modeling, and docs, in v3 over the next few months.</p><p>We are also working on an enterprise teams product, with enhanced Prism functionality — will share details soon (or please reach out to us in the meantime if this sounds interesting!).</p><p>The Stoplight Team</p><p>@marbemac, @pytlesk4, @chrisnlott, @vazhaom</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3b88242cf9cc" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/introducing-scenarios-3b88242cf9cc">Introducing Scenarios</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A big v2 update, and goodbye to v1]]></title>
            <link>https://medium.com/api-corner/a-big-v2-update-and-goodbye-to-v1-f8b51f7dbd08?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/f8b51f7dbd08</guid>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Wed, 17 Aug 2016 01:10:37 GMT</pubDate>
            <atom:updated>2017-02-26T23:12:56.516Z</atom:updated>
            <content:encoded><![CDATA[<p>Thanks to all who participated in the beta of our version 2 tooling! We received a tremendous amount of feedback, and it was a great success. We’ve turned that feedback into our final big v2 update, which is rolling out today.</p><p><strong>Important Dates</strong></p><ul><li><strong>August 18th:</strong> Shutdown of v1, free beta of v2 ends (billing is enforced now).</li><li><strong>August 19th, 9PM PST:</strong> 30 minutes of scheduled maintenance on the Stoplight app, during which it will not be available. Documentation hosted with API Docs will not be affected.</li></ul><p><strong>Updates to v2</strong></p><p>This update combines the left nav and sidebars into a single column, with much clearer navigational elements. It also fixes a slew of bugs, and introduces a few new features, some of which include:</p><ul><li>Shared models &amp; design at the workspace level. While this was available in the initial v2 release, it was quite hidden and most users did not notice it.</li><li>Spec import when creating new API versions.</li><li>A new learn area.</li><li>A new prism settings panel.</li></ul><p><strong>Immediate Plans</strong></p><p>We will be focusing our efforts on the following 5 areas:</p><ul><li>Writing articles and producing videos, covering a variety of topics related to the Stoplight tooling.</li><li>Implementing long requested smaller features, some of which include custom (and multiple) mimetypes, and swagger extension support.</li><li>Improving our API specification support, and allowing for direct specification editing within Stoplight.</li><li>Improving API docs.</li><li>Github sync.</li></ul><p>Please send questions or comments to <a href="https://twitter.com/stoplightio">@stoplightio</a> or support@stoplight.io.</p><p>The Stoplight Team <br>Marc, Chris, Tom, and Vazha</p><p><em>Originally published at </em><a href="http://stoplight.ghost.io/a-big-v2-update-and-goodbye-to-v1/"><em>stoplight.ghost.io</em></a><em> on August 17, 2016.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f8b51f7dbd08" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/a-big-v2-update-and-goodbye-to-v1-f8b51f7dbd08">A big v2 update, and goodbye to v1</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stoplight ❤ Windows and Linux]]></title>
            <link>https://medium.com/api-corner/stoplight-windows-and-linux-97fe9bdbb5e7?source=rss-4b40032f3cfc------2</link>
            <guid isPermaLink="false">https://medium.com/p/97fe9bdbb5e7</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[cors]]></category>
            <dc:creator><![CDATA[Stoplight]]></dc:creator>
            <pubDate>Mon, 25 Jul 2016 17:28:55 GMT</pubDate>
            <atom:updated>2017-02-26T23:23:17.670Z</atom:updated>
            <content:encoded><![CDATA[<p>One of our most requested features has been Windows and Linux support for the Stoplight desktop app. Today, we are excited to finally release builds for Windows (64 bit) and Linux (32 and 64 bit)!</p><p>Our desktop app makes working behind firewalls or with local servers easy, and stores API request data locally, alleviating the most common security concerns.</p><p>You can download the Stoplight desktop app appropriate for your current operating system by visiting <a href="https://download.stoplight.io/">https://download.stoplight.io</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*fJcxNL4FMJ7DKqzZ.png" /></figure><p>The Stoplight desktop app:</p><ul><li>Syncs in realtime with the web app, and all of your team members.</li><li>Manages an instance of the Prism proxy on your computer for you (by default, it runs Prism on <a href="http://localhost:4010/">http://localhost:4010</a>).</li><li>Makes it easy to send HTTP requests from behind firewalls, or to local development servers.</li><li>Takes care of those pesky CORS issues.</li><li>Makes it easy to run tests from behind firewalls, or against local development servers.</li><li>Stores HTTP request data offline, on your computer. API requests and tests sent/run through the local Prism instance never touch our servers! This solves many security issues.</li></ul><p>Let us know what you think by tweeting <a href="https://twitter.com/stoplightio">@stoplightio</a>, or emailing support@stoplight.io.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=97fe9bdbb5e7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/api-corner/stoplight-windows-and-linux-97fe9bdbb5e7">Stoplight ❤ Windows and Linux</a> was originally published in <a href="https://medium.com/api-corner">Stoplight API Corner</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>