├── .gitignore ├── LICENSE ├── README.md ├── galaxy └── api-first │ ├── customer.json │ ├── customers.yaml │ └── training.md └── student ├── classroom-kit.md ├── lesson-visualizer.jpg └── student.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Postman Learning Resources 2 | 3 | Welcome to the Postman templates repo! Here you will find templates and other resources for learning and teaching with Postman. 4 | -------------------------------------------------------------------------------- /galaxy/api-first/customer.json: -------------------------------------------------------------------------------- 1 | { 2 | "openapi": "3.0.0", 3 | "info": { 4 | "version": "1.0", 5 | "title": "Customers", 6 | "description": "This is a spec file for Postman Galaxy 2021 API First training! Open the raw file and save it locally. In Postman, navigate to **APIs** and create a new API, giving it the name \"Customers\", version \"1.0\" and import your downloaded file." 7 | }, 8 | "servers": [ 9 | { 10 | "url": "https://669950d5-2da7-4207-a56c-bfe0825afafb.mock.pstmn.io" 11 | } 12 | ], 13 | "paths": { 14 | "/customer": { 15 | "get": { 16 | "summary": "Retrieve details for a particular customer", 17 | "operationId": "getCustomer", 18 | "tags": [ 19 | "customer" 20 | ], 21 | "parameters": [ 22 | { 23 | "name": "id", 24 | "in": "query", 25 | "description": "Customer ID", 26 | "required": true, 27 | "schema": { 28 | "type": "integer", 29 | "minimum": 1 30 | } 31 | } 32 | ], 33 | "responses": { 34 | "200": { 35 | "description": "Details of the requested customer", 36 | "content": { 37 | "application/json": { 38 | "schema": { 39 | "$ref": "#/components/schemas/Customer" 40 | } 41 | } 42 | } 43 | } 44 | } 45 | }, 46 | "post": { 47 | "summary": "Add a new customer", 48 | "operationId": "addCustomer", 49 | "tags": [ 50 | "customer" 51 | ], 52 | "requestBody": { 53 | "description": "Details of the new customer", 54 | "required": true, 55 | "content": { 56 | "application/json": { 57 | "schema": { 58 | "$ref": "#/components/schemas/Customer" 59 | } 60 | } 61 | } 62 | }, 63 | "responses": { 64 | "201": { 65 | "description": "Confirmation of the added customer", 66 | "content": { 67 | "application/json": { 68 | "schema": { 69 | "$ref": "#/components/schemas/Confirm" 70 | } 71 | } 72 | } 73 | } 74 | } 75 | } 76 | } 77 | }, 78 | "components": { 79 | "schemas": { 80 | "Customer": { 81 | "type": "object", 82 | "required": [ 83 | "id", 84 | "name", 85 | "company" 86 | ], 87 | "properties": { 88 | "id": { 89 | "type": "integer" 90 | }, 91 | "name": { 92 | "type": "string", 93 | "example": "{{$randomFullName}}" 94 | }, 95 | "tag": { 96 | "type": "string", 97 | "example": "{{$randomBsNoun}}" 98 | }, 99 | "role": { 100 | "type": "string", 101 | "example": "{{$randomJobTitle}}" 102 | }, 103 | "company": { 104 | "type": "string", 105 | "example": "{{$randomCompanyName}}" 106 | }, 107 | "vertical": { 108 | "type": "string", 109 | "example": "{{$randomProductName}}" 110 | } 111 | } 112 | }, 113 | "Confirm": { 114 | "type": "object", 115 | "required": [ 116 | "message" 117 | ], 118 | "properties": { 119 | "message": { 120 | "type": "string", 121 | "example": "New customer added!" 122 | } 123 | } 124 | } 125 | } 126 | } 127 | } 128 | -------------------------------------------------------------------------------- /galaxy/api-first/customers.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | version: '1.0' 4 | title: Customers 5 | description: 'This is a spec file for Postman Galaxy 2021 API First training! Open the raw file and save it locally. In Postman, navigate to **APIs** and create a new API, giving it the name "Customers", version "1.0" and import your downloaded file.' 6 | servers: 7 | - url: 'https://669950d5-2da7-4207-a56c-bfe0825afafb.mock.pstmn.io' 8 | paths: 9 | /customer: 10 | get: 11 | summary: Retrieve details for a particular customer 12 | operationId: getCustomer 13 | tags: 14 | - customer 15 | parameters: 16 | - name: id 17 | in: query 18 | description: Customer ID 19 | required: true 20 | schema: 21 | type: integer 22 | minimum: 1 23 | responses: 24 | '200': 25 | description: Details of the requested customer 26 | content: 27 | application/json: 28 | schema: 29 | $ref: '#/components/schemas/Customer' 30 | post: 31 | summary: Add a new customer 32 | operationId: addCustomer 33 | tags: 34 | - customer 35 | requestBody: 36 | description: Details of the new customer 37 | required: true 38 | content: 39 | application/json: 40 | schema: 41 | $ref: '#/components/schemas/Customer' 42 | responses: 43 | '201': 44 | description: Confirmation of the added customer 45 | content: 46 | application/json: 47 | schema: 48 | $ref: '#/components/schemas/Confirm' 49 | components: 50 | schemas: 51 | Customer: 52 | type: object 53 | required: 54 | - id 55 | - name 56 | - company 57 | properties: 58 | id: 59 | type: integer 60 | name: 61 | type: string 62 | example: '{{$randomFullName}}' 63 | tag: 64 | type: string 65 | example: '{{$randomBsNoun}}' 66 | role: 67 | type: string 68 | example: '{{$randomJobTitle}}' 69 | company: 70 | type: string 71 | example: '{{$randomCompanyName}}' 72 | vertical: 73 | type: string 74 | example: '{{$randomProductName}}' 75 | Confirm: 76 | type: object 77 | required: 78 | - message 79 | properties: 80 | message: 81 | type: string 82 | example: 'New customer added!' 83 | -------------------------------------------------------------------------------- /galaxy/api-first/training.md: -------------------------------------------------------------------------------- 1 | # Postman Galaxy 2021 - API First Training 2 | 3 | This API includes supporting resources for the API First training session at Postman Galaxy 2021! During the session you're going to work through generating collections from this API specification. 4 | 5 | On completion of your submission for this training, you will receive the [Postman API First](https://badgr.com/public/badges/4ZMWYUmITU20Lf9JdAR6Xw) badge! 6 | 7 | > 📌 Adopting a best practice approach to your API development process isn't as much of a hurdle as you might expect. By starting from an OpenAPI specification in Postman, you can generate multiple other components within a robust framework that delivers reliability and performance. Having a spec act as your single source of truth sets your API product or project up for governance, maintainability, effective adoption, and ultimately a competitive advantage. 8 | 9 | **Before you start, make sure you have the Postman agent installed–we're going to be working in [Postman on the web](http://go.postman.co/build/) (not the desktop app). Make sure you also create a new workspace for the session–and make sure you choose a Public workspace, so that you can share it later, forwarding the link to request your API First certification.** 10 | 11 | ## The Customers specification 12 | 13 | Navigate to the public workspace for the session: [bit.ly/postman-training](http://bit.ly/postman-training) 14 | 15 | In __APIs__, select __Customers__. Select the __Define__ tab. 16 | 17 | You don't need to worry too much about the detail in the spec, but note the following: 18 | 19 | * If you check out the base URL you'll see it's initially going to hit a mock API we set up in advance, but you'll be replacing this later with your own mock. 20 | * It includes two initial endpoints, one for retrieving a customer, and one for adding a new customer. 21 | * The request and response body schema are defined in the `components` at the end of the spec. 22 | * The examples include dynamic variable references (with the syntax `{{$randomValue}}`) that Postman will use to generate random property values in the docs and mocks for the collections we generate. 23 | 24 | Take a quick look at the tabs in the **API** builder–we'll get to know them better as we work through the session. We'll generate collections for a few different purposes including documentation and testing, all based on the spec, and link elements such as mock servers and monitors to it so that it becomes our single source of truth for the API. Notice that you can comment and share the API to collaborate with teammates–Postman can also generate reports on your API to give stakeholders an overview of how it's performing. 25 | 26 | ## 1. Import the starter spec 27 | 28 | In the **Define** tab > **Copy** the content of the specification using the button at the top right of the edit area (you can toggle back and forth between it and the API __Overview__ here). 29 | 30 | In the new workspace you created for this session (you might want to keep this tab open as well so that you can refer to the info here), choose **APIs** on the left, and click **+** to create a new API. 31 | 32 | * `Customers` as the name. 33 | * `1.0` as the version. 34 | * `OpenAPI 3.0` as the schema type. 35 | * `JSON` as the schema format. 36 | * Create your new API and paste in the content you copied (replace the default contents). 37 | 38 | > You can sync your Postman API with a linked spec, for example via GitHub integration. 39 | 40 | **Save** the API–Postman will validate your schema and alert you to any issues within it. Open the __Define__ tab to see the specification JSON. 41 | 42 | > 📌 Try introducing a syntax error into your spec file, or add an invalid element, to see how Postman highlights validation issues. Click the alert along the bottom to see more detail. As you edit, the validation will update. The editor will also prompt you with element suggestions as you type. 43 | 44 | ## 2. Generate a documentation collection 45 | 46 | Let's go ahead and generate a Postman collection from the spec. Click **Generate collection**. First let's create a collection we can use to work on documentation for the API. 47 | 48 | * Enter the name `Customer docs`. 49 | * Select **API Documentation**. 50 | 51 | > 📌 Take a quick look at the advanced options–we don't need them for now but you can tailor the detail of how your collections generate from the spec. 52 | 53 | Click **Generate Collection** and Postman will add it in **Collections**. _If you click **View documentation** in the notification you can see the docs straight away, or open the collection from the left of Postman and open the docs using the button on the right._ **Keep the complete documentation view open in a tab as you work through the steps.** 54 |

55 | Open the new collection and take a look at how the requests have been generated. 56 | 57 | 67 |

Try sending the requests (make sure the desktop agent is selected). Initially the requests will send to the mock 68 | server we created before the session, but you'll send to your own mock later.

69 |

Validate

70 |

Postman will validate your collections against the linked spec as you work, but while you're in the request 71 | builder you'll only see an alert if your request is failing validation. Let's introduce an error 72 | intentionally so that we can see the validation in action.

73 | 80 |

View the docs

81 |

Let's have a look at how the spec information populates into the documentation for the collection. With a request 82 | open, click the little docs icon at the top right.

83 |

Postman automatically indicates your request and response details including parameters, bodies, headers, and auth. 84 | You can add details by editing the information inline–edit a request description (you can use markdown) and save it. 85 | Click the link to view the complete docs to see how the collection as a whole is represented in docs form.

86 |

Check out the examples in your collection docs parameters and request / response bodies–they use the examples from 87 | your spec. Since we used the Postman dynamic variable syntax in the spec, your examples will dynamically generate 88 | random values whenever your docs are viewed. Try closing the docs tab and opening again to see this in action.

89 |
90 |

📌 The example name for a response comes from your API spec description for the response. If you have more than 91 | one response listed for a request, Postman will generate an example for each one, and your docs will present 92 | them via a drop-down list.

93 |
94 |

Pop back into the Customers API and open the Develop tab. Your linked docs collection will be 95 | listed. Click to validate it–it should be valid.

96 | 104 |

We will add more linked collections and other elements to the API as we work through the session.

105 |

3. Add a new endpoint

106 |

Let's make a change to the spec. We have endpoints for adding and retrieving a customer, but we need one for 107 | retrieving a list of customers.

108 |

In APIs > Customers > Define. Add a new endpoint inside 109 | paths, after the post request (adding a comma before the previous element–you can hit the 110 | Beautify button at the top right to clean up your indentation).

111 | 
"/customers": {
112 |     "get": {
113 |         "summary": "Retrieve details for all customers",
114 |         "operationId": "listCustomers",
115 |         "tags": [
116 |             "customer"
117 |         ],
118 |         "responses": {
119 |             "200": {
120 |                 "description": "Details of all customers",
121 |                 "content": {
122 |                     "application/json": {
123 |                         "schema": {
124 |                             "$ref": "#/components/schemas/CustomerList"
125 |                         }
126 |                     }
127 |                 }
128 |             }
129 |         }
130 |     }
131 | }
132 |

The endpoint is going to be at the path /customers and will return a list of customer objects 133 | (referencing the existing Customer schema). Add the CustomerList schema in 134 | components > schemas after the existing schema elements.

135 | 
"CustomerList": {
136 |     "type": "array",
137 |     "items": {
138 |         "$ref": "#/components/schemas/Customer"
139 |     }
140 | }
141 |

Save the spec. Back in Develop, validate the linked docs collection again. Click to 142 | Review Issues. Select the suggested changes and confirm, then navigate back to the collection to 143 | see the new endpoint.

144 |

4. Create a mock collection

145 |

Next we're going to create a collection we can use with a mock server we're also going to create. 146 |

When we create the mock server, its address will be stored in a variable, and we will be able to switch between the 147 | original server and the new mock using an environment.

148 |

Save the spec and Generate Collection again, this time choosing API 149 | Mocking. Give your collection the name Customer mocks and Generate it. 150 |

151 |

Name your mock server Mock customers and check the box to save the URL as an environment variable. 152 | Postman will create a new environment for the mock as well as generating the mock and collection.

153 |

Use environments

154 |

Select the new environment, it will have the same name as the mock server: Mock customers. Click the eye 155 | button to see that it has a url variable with the address of your new mock server–edit the 156 | variable name, changing it to baseUrl.

157 |

Select the Customer mocks collection and open the collection Variables. The 158 | baseUrl includes the original URL from the spec, but by selecting the environment, the requests will 159 | reference the mock URL instead, because Postman scope means that the environment value overrides the collection 160 | value.

161 |
162 |

📌 You can also link Environments to a spec in the API Developtab.

163 |
164 |

Send one of the requests in the mock collection. This time it will hit the new mock you created (you 165 | can check where it sent in the Console).

166 |

Author examples

167 |

You can edit your examples, for example if you prefer not to use the dynamic variables, or if you want to use a 168 | different one. Let's edit an example in the new mock collection to make it invalid.

169 | 173 |

In the API Develop tab, validate the linked mock. Click to review the issues and make the suggested 174 | changes, confirming and returning to the workspace / spec. Make sure you reselect the mocks environment if you 175 | leave and return to the workspace.

176 |

Edit the spec

177 |

Back in the spec, let's make a change to the examples and see how that propagates to the collection. Add a new 178 | status string property to the Confirm schema and make it required, so that the whole 179 | schema looks like this:

180 | 
"Confirm": {
181 |     "type": "object",
182 |     "required": [
183 |         "message",
184 |         "status"
185 |     ],
186 |     "properties": {
187 |         "message": {
188 |             "type": "string",
189 |             "example": "New customer added!"
190 |         },
191 |         "status": {
192 |             "type": "string",
193 |             "example": "OK"
194 |         }
195 |     }
196 | },
197 |

Save the spec and go back into the POST request in the mock 198 | collection–Send it.

199 |

Go back into the API Develop tab and validate the mock collection again, reviewing the issues, 200 | making the changes, and navigating back to the collection. Send the mocks POST request 201 | again–the new property should be returned.

202 |

5. Add a test suite

203 |

Combining test suites with an API-spec driven workflow builds a level of consistency and compliance into your API 204 | development and deployment pipeline.

205 |

The final collection we're going to generate is for testing. Back in the API, hit Generate 206 | Collection again, this time choosing Contract Testing, with the name 207 | Customer contract tests.

208 |

In the new collection, open the GET request that returns a particular customer. In the 209 | Tests tab for the request, add a test from the snippets on the right (click < 210 | if they don't display by default). Add Status code: Code is 200 to the tests, 211 | Save, and Send the request. The test should pass.

212 |

Add the same snippet to the other two requests, but in the POST request change the code to 213 | 201 as follows:

214 | 
pm.test("Status code is 201", function () {
215 |     pm.response.to.have.status(201);
216 | });
217 |

All of your requests should now have a test of some kind in them–to add one that looks a little more like a real 218 | contract test let's define a schema and validate against it in the GET request that retrieves a 219 | particular customer.

220 | 
const schema = {
221 |   "properties": {
222 |     "id": {
223 |         "type": "integer"
224 |     },
225 |     "company": {
226 |         "type": "string"
227 |     },
228 |     "name": {
229 |         "type": "string"
230 |     }
231 |   }
232 | };
233 | pm.test("Schema is valid", function() {
234 |   pm.response.to.have.jsonSchema(schema);
235 | });
236 |

Save and Send the request–it should pass. Try making it fail by changing the 237 | type for id to boolean.

238 |
239 |

📌 Tip: leave the test failing so that you see more interesting results when you add a monitor next.

240 |
241 |

Add a final test to the customer folder–this will run for every request inside the folder. In the 242 | Tests for the folder, add the following to test the response time:

243 | 
pm.test("Response time is less than 200ms", function () {
244 |     pm.expect(pm.response.responseTime).to.be.below(200);
245 | });
246 |

Try running your collection in the collection runner–select the collection and hit Run, running with 247 | the default options. Check out the output, selecting requests to drill down into the detail (which you can also do 248 | in the Console).

249 |

6. Add a monitor

250 |

Finally, let's monitor the API. In the API Observe tab, click Add monitor > 251 | Create new monitor. Click Use existing collection and choose the 252 | Customer contract tests collection.

253 |
254 |

📌 A monitor is similar to using the collection runner, or Newman. It runs your collection on a schedule and 255 | alerts you to any failed tests by notification email.

256 |
257 |

Give your monitor the name Monitor customers, select the Mock customers environment, choose 258 | a frequency, and create your monitor.

259 |

Rather than waiting for the scheduled time, hit 260 | Run! There will be a short delay while your monitor runs but when it completes you will see an 261 | overview of the test results.

262 |

Navigate back to the API and click the monitor name in Observe. You will see an overview 263 | of the monitor runs. Click a run and scroll down to see the detail of any test fails. You can filter the results and 264 | drill down to individual requests.

265 |

7. Complete your submission

266 |

Once you have all of your collections generated from your spec as outlined above and you're happy with your 267 | workspace, you can go ahead and share it (making sure it's set to Public in the workspace 268 | overview), then share the link to get your API First badge and swag!

269 |

When your workspace is public, anyone can open it in the browser and fork your collections to edit or send the 270 | requests in them. You can copy the workspace link from your browser address bar after making it public.

271 |
272 |

📌 Note that a Postman team admin can set the account to require approval to make a workspace public via the 273 | Community Manager role.

274 |
275 |

Fill out the form bit.ly/submit-api-first (if anything is missing we will 276 | follow up with you).

277 | -------------------------------------------------------------------------------- /student/classroom-kit.md: -------------------------------------------------------------------------------- 1 | # Postman Classroom Teaching Kit 2 | 3 | _This kit is for educators looking to teach Postman in their programs._ 4 | 5 | Thanks for your interest in teaching Postman in your classroom! 🎓🎒🚀 6 | 7 | Here you will find supporting resources you can use to build Postman into your learning experiences. You are welcome to use these resources as they are or to fork and remix them. 8 | 9 | ## Postman Classroom Template 10 | 11 | The Postman Classroom template walks learners through API and Postman fundamentals. Learners can import the template, send the first request, and be guided through next steps by the response data via the Postman visualizer. 12 | 13 | ![Visualizer](lesson-visualizer.jpg) 14 | 15 | A template is a Postman collection that is published online and that you can [import into Postman](https://learning.postman.com/docs/getting-started/importing-templates/). Here's how the classroom template works: 16 | 17 | * The template uses an API hosted on [Glitch](https://glitch.com/), and a Postman [mock server](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/). 18 | * The API / mock endpoints are designed specifically for learning, so the response data includes information about the request, together with next steps. 19 | * The template includes a script for presenting the response information in the Postman [Visualizer](https://learning.postman.com/docs/sending-requests/visualizer/), so that it renders as a tutorial, with text, images, and example code. 20 | * The learner completes the collection by editing request components, and adding new requests. 21 | * Each Postman collection is represented as JSON data, which you can retrieve via a public URL. When they have completed the steps, the learner copies their collection's public link into the final request to retrieve the JSON data. The request runs a test script on the collection JSON to check for completeness. The tests will pass if the learner has completed all of the required collection edits. 22 | 23 | The classroom template is in the Postman Student Program workspace–available at a short url: 24 | 25 | * [**bit.ly/student-workspace**](http://bit.ly/student-workspace) 26 | 27 | _If you plan on using the template in your classroom please try it out in Postman yourself first. Select the __Postman Classroom__ collection in __Collections__ on the left, and click __Fork__ to copy it into your own workspace. Open the first request, send it, and open the Visualize view on the response. The instructions guide you through the steps–but you are also welcome to add your own context or any additional info you feel learners will benefit from._ 28 | 29 | Please check out the [Postman classroom curriculum](student.md) for pointers on topics. The list is generic but you are welcome to choose topics to suit your own programs and learning contexts. If you'd like to make suggestions on the curriculum or classroom experience [please submit an issue](https://github.com/postmanlabs/templates/issues)! 30 | 31 | ## Checking Student Progress 32 | 33 | If you want to help students complete their student expert collections or check progress, you can ask them to share their collection links using the following steps: 34 | 35 | * Select the collection 36 | * Click __Share__ 37 | * Click __Get public link__ 38 | * Generate or update link (making sure the students update after every time they make a change as it's just a snapshot) 39 | * Copy the link 40 | 41 | If the students send you their links you can import their collections into Postman by clicking __Import__ > __Link__. Then you can run the final request `Test collection` to check for completeness. 42 | 43 | > If you want to test a batch of collections you can do so using a data file–add each collection link on a new line in a `.csv` file with `your-collection-link-here` on the first line. Import the Student Expert or Classroom collection into your workspace (from [bit.ly/student-workspace](https://bit.ly/student-workspace)). Select the collection and click __Run__, choose the data file, and run–to identify any links that are failing, click the collection run output. 44 | 45 | ## Postman Classroom Slides 46 | 47 | The slide deck is available at a short url—it's in Google Slides but you can download and edit it however you like. 48 | 49 | * [**bit.ly/postman-classroom-slides**](http://bit.ly/postman-classroom-slides) 50 | 51 | ## Postman Support and Community 52 | 53 | Please [let the community know](https://community.postman.com/) about your API learning programs! 54 | 55 | You can find additional info about all things Postman in the official resources: 56 | 57 | * [Learning Center](https://learning.postman.com/) 58 | * [Community Forum](https://community.postman.com/) 59 | * [Postman YouTube channel](https://www.youtube.com/postmanapidevelopment) 60 | 61 | If you're using Postman in your classroom you are welcome to apply for access to additional features via the educator's plan. The Postman team will send you a link for access within a couple of weeks when you apply to join the classroom program! 🎉 62 | -------------------------------------------------------------------------------- /student/lesson-visualizer.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/postmanlabs/templates/20d2a8e3f7b8a3d4ab499a0c056bdc4a891c5645/student/lesson-visualizer.jpg -------------------------------------------------------------------------------- /student/student.md: -------------------------------------------------------------------------------- 1 | # Postman Classroom Curriculum 2 | 3 | This curriculum is for teaching Postman in classroom contexts. 4 | 5 | ## Pre-requisites / preparatory topics 6 | 7 | API basics can be assumed or taught as intro material depending on course context: 8 | 9 | * Server vs client 10 | * Testing concepts 11 | * Data structures (JSON) 12 | * Variable concepts 13 | * API concepts including request, response, endpoint 14 | 15 | ## Core Postman topics 16 | 17 | * Building requests 18 | * Variety of methods (including GET, POST, PUT, DELETE) 19 | * Parameters (including query and path) 20 | * Body data 21 | * Authorization 22 | * Viewing responses in Postman 23 | * Variables 24 | * Declaring at different scopes (collection and environment) 25 | * Referencing in requests (in address, parameters, optionally body, scripts) 26 | * Passing data between requests 27 | * Collections 28 | * Editing documentation 29 | * Importing from templates / network 30 | * Testing 31 | * Basic assertions in test scripts 32 | * Using the console 33 | * Running collections 34 | * Building workflows (changing execution order with setNextRequest) 35 | 36 | ## Follow-up / optional topics 37 | 38 | * Additional request configurations (e.g. headers, other parameter and body data types) 39 | * Mocks (including examples) 40 | * Monitors 41 | * Collaboration (including workspaces, version control) 42 | * Visualizer 43 | * Codegen 44 | * API schema 45 | * Newman 46 | * CI/CD 47 | 48 | Optional topics can be tailored to course context, prior learning and related outcomes. 49 | --------------------------------------------------------------------------------