TerribleDev/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update validation.md

Browse Source
This commit is contained in:
Robert Wallach
2018-01-26 15:49:56 -06:00
committed by GitHub
parent 3b66566ebe
commit 6bd767f92c
1 changed files with 16 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
articles/prism/validation.md
View File

@@ -1,12 +1,15 @@
# Setting up a hosted prism contract server
# Setting up a Hosted Prism Contract Server
Contract servers are a powerful tool in a developer's toolbox. They use your OAS (Swagger 2) and JSON Schema definitions to validate HTTP traffic passing through your API. You can use them to:
1. **Add contract tests to an existing test suite.** Already have a test suite? No problem! Point your tests at the contract test server, and it can annotate responses with the contract test results. Your test suite just has to check for these response headers and fail appropriately.
2. **Monitor traffic for anomalies.** Know _when_ your implementation breaks instantly, and _why_. By sending all your traffic through your contract server, you can flag that 1 in 1000 request anomaly.
3. **Detect changes in 3rd party APIs.** APIs (particularly microservices) usually make calls to other APIs. These dependencies can be scary because you have no control over when they change. With contract servers sitting in between you (the consume) and the external API, you can be alerted when the external API changes.
1. **Add Contract Tests to an Existing Test Suite**
- Already have a test suite? No problem! Point your tests at the contract test server, and it can annotate responses with the contract test results. Your test suite just has to check for these response headers and fail appropriately.
2. **Monitor Traffic for Anomalies**
- Know _when_ your implementation breaks instantly, and _why_. By sending all your traffic through your contract server, you can flag that 1 in 1000 request anomaly.
3. **Detect Changes in 3rd Party APIs**
- APIs (particularly microservices) usually make calls to other APIs. These dependencies can be disconcerting because you have no control over when they change. With contract servers positioned between you (the consumer) and the external API, you can be alerted when the external API changes.
> **Real world use case.** Still not convinced, then head on over to Sendgrid and learn how they used contract servers to power their [integration tests](https://sendgrid.com/blog/stoplight-io-to-test-api-endpoints) for their 7 SDKs.
> **Real World Use Case** - Still not convinced, then head on over to Sendgrid and learn how they used contract servers to power their [integration tests](https://sendgrid.com/blog/stoplight-io-to-test-api-endpoints) for their 7 SDKs.
If you aren't familiar with JSON Schema, we highly recommend you head [here](https://spacetelescope.github.io/understanding-json-schema/) first.
@@ -14,28 +17,28 @@ If you are coming from Stoplight Classic (v2), you will notice that there is a l
## Hosted Contract Server Steps
_Note: We plan to introduce templates to the Stoplight editor file creation process soon. This feature will automate most of the steps below, and turn mock server creation into a one-click solution._
_Note: We plan to introduce templates to the Stoplight editor file creation process soon. This feature will automate most of the steps below and turn mock server creation into a one-click solution._
_For this article we are validate a service that already exists. It is just a simple API representing a todos list manager that is running at http://todos.stoplight.io. We have created a OAS Specification for it already and you can download it [here](https://exporter.stoplight.io/3351/master/todos.oas2.yml)._
_For this article we will validate a service that already exists. It is just a simple API representing a todos list manager that is running at http://todos.stoplight.io. We have created an OAS Specification for it already and you can download it [here](https://exporter.stoplight.io/3351/master/todos.oas2.yml)._
1. Let's create a new project, create a new spec and name it `todos.oas2`, and paste the json from the spec above in the code editor.
1. Let's create a new project, create a new spec, name it `todos.oas2`, and paste the JSON from the spec above in the code editor.
![](../../assets/gifs/validation-todos-contract-guide.gif)
2. Create a new **Prism instance file** in the project. Name it `todos.contract.prism`.
3. Prism instances are made up of APIs and Rules, you can learn more about them here. Add an API to the Prism instance, and connect the `todos.oas2` specification that you created earlier. Also, let's change the `id` to `todos`, and set the _Upstream URL_ to _http://todos.stoplight.io_. The Upstream URL is where the contract server will forward incoming requests.
3. Prism instances are made up of APIs and Rules, you can learn more about them here. Add an API to the Prism instance and connect the `todos.oas2` specification that you created earlier. Also, let's change the `id` to `todos` and set the _Upstream URL_ to _http://todos.stoplight.io_. The Upstream URL is where the contract server will forward incoming requests.
![](../../assets/gifs/validation-todos-prism-api.gif)
4. Next, add a **new rule** that you will setup to power the validation. Rules simply apply scenarios to HTTP traffic passing through the Prism instance.
5. Once you have created a new rule, you need to connect it to the API we added earlier. To do that, click on the `apis` dropdown input, and select the previously created API. Connecting the rule to the API you defined earlier makes the OAS file available to scenarios in the rule.
6. Finally, you need to add a **scenario** that will actually perform the validation. We have an official Stoplight validate scenario [here](https://next.stoplight.io/stoplight/prism?edit=%23%2Fscenarios%2validate), which makes it easy to get started. Add a scenario to the `after` section of your rule. Select `another project` in the first dropdown, and then search for `prism`. The file in that project you are looking for is `helpers.prism.yml`, and the specific scenario is called `validate`. This validate scenario should suit most of your needs it will check the request/response headers, request/response body, and request path parameters and query strings. It will add response headers to the HTTP request on the way back to the consumer with the results of the validation. For advanced use cases please send us a message and we would love to help out.
5. Once you have created a new rule, you need to connect it to the API we added earlier. To do that, click on the `apis` dropdown input and select the previously created API. Connecting the rule to the API you defined earlier makes the OAS file available to scenarios in the rule.
6. Lastly, you need to add a **scenario** that will actually perform the validation. We have an official Stoplight validate scenario [here](https://next.stoplight.io/stoplight/prism?edit=%23%2Fscenarios%2validate), which makes it easy to get started. Add a scenario to the `after` section of your rule. Select `another project` in the first dropdown and then search for `prism`. The file you are looking for within that project is `helpers.prism.yml` and the specific scenario is called `validate`. This validate scenario should suit most of your needs. It will check the request/response headers, request/response body, request path parameters, and query strings. It will also add response headers to the HTTP request on the way back to the consumer with the results of the validation. For advanced use cases, please send us a [message](). We would love to help out!
![](../../assets/gifs/validation-todos-prism-rule.gif)
7. Save, and let's verify that your contract server is working. Click on Home, and let's Send a Test Request to `GET /todos`.
7. Save and let's verify that your contract server is working. Click on Home and let's Send a Test Request to `GET /todos`.
_Stoplight's visual editior makes it really easy to debug reqeust/response, if you go and look at the response headers, specifically `Sl-Valid` it should be `false`. This means that according to your api specification the reqeust/response isn't valid, aka the contract test failed. You can find out why by inspecting the `Sl-Validation-Messages`. For the purpose of this article the messages are below, and it looks like user is a requeired property and it is missing._
_Stoplight's visual editior makes it really easy to debug reqeust/response. If you go and look at the response headers, specifically `Sl-Valid` it should be `false`. This means that according to your api specification the reqeust/response isn't valid, aka the contract test failed. You can find out why by inspecting the `Sl-Validation-Messages`. For the purpose of this article the messages are below, and it looks like user is a requeired property and it is missing._
```js
// Sl-Validation-Messages