├── .gitignore ├── README.md ├── valentines-book-list.md ├── valentines-book-list-openapi.yaml ├── simple-grocery-store-api.md └── simple-grocery-store-openapi.yaml /.gitignore: -------------------------------------------------------------------------------- 1 | .vscode 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Postman-Complete-Guide-API-Testing -------------------------------------------------------------------------------- /valentines-book-list.md: -------------------------------------------------------------------------------- 1 | # Valentine's Book List API 2 | 3 | This API allows you to view the books that Valentine has read or plans to read. 4 | 5 | The API is available at `https://valentines-book-list.glitch.me` 6 | 7 | ## Endpoints 8 | 9 | - [Status](#Status) 10 | - [Books](#Books) 11 | - [Get a book list](#Get-a-book-list) 12 | 13 | 14 | ## Status 15 | 16 | **`GET /status`** 17 | 18 | Returns the status of the API. Example response: 19 | 20 | ``` 21 | { 22 | "status": "UP" 23 | } 24 | ``` 25 | 26 | Status `UP` indicates that the API is running as expected. 27 | 28 | No response or any other response indicates that the API is not functioning correctly. 29 | 30 | ## Books 31 | 32 | ### Get a book list 33 | 34 | **`GET /books/lists`** 35 | 36 | Returns a list of books. Requires authentication. 37 | 38 | This endpoint uses pagination to handle the returned results. Paginating the results ensures responses are easier to handle. Each response will indicate the total number of results, the current page, and the total number of pages. 39 | 40 | **Parameters** 41 | 42 | | Name | Type | In | Required | Description | 43 | | ----------- | ------- | ----- | -------- | -----------------------------------------------------------------------------------------------------------| 44 | | `list` | string | query | Yes | Specifies the list you want to retrieve. Must be one of: favourite-books, non-fiction, wishlist, fiction. | 45 | | `page` | integer | query | No | Specifies the page you wish to retrive from the entire result set. | 46 | 47 | **Status codes** 48 | 49 | | Status code | Description | 50 | |-----------------|-----------------------------------------------------| 51 | | 200 OK | Indicates a successful response. | 52 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 53 | 54 | Example response: 55 | 56 | ``` 57 | { 58 | "status": "OK", 59 | "num_results": 17, 60 | "page": 1, 61 | "total_pages": 4, 62 | "results": [ 63 | { 64 | "title": "Crush It!: Why NOW Is the Time to Cash In on Your Passion", 65 | "category": [ 66 | "non-fiction" 67 | ], 68 | "type": "audio", 69 | "author": "Gary Vaynerchuk", 70 | "release_year": 2010, 71 | "rating": "7" 72 | }, 73 | ... 74 | ] 75 | ] 76 | ``` 77 | 78 | 79 | ## API Authentication 80 | 81 | Some endpoints require authentication. 82 | 83 | The endpoints that require authentication expect the API key to be provided as a query parameter named `api-key`. 84 | -------------------------------------------------------------------------------- /valentines-book-list-openapi.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.3 2 | info: 3 | title: Valentine's Book List API 4 | description: | 5 | This API allows you to view the books that Valentine has read or plans to read. 6 | 7 | The API is available at `https://valentines-book-list.glitch.me` 8 | version: "acc411151ad8c42b47a9a37b91f1415aecd2a49e" 9 | servers: 10 | - url: https://valentines-book-list.glitch.me 11 | paths: 12 | /status: 13 | get: 14 | tags: ["status"] 15 | summary: Returns the status of the API. Example response 16 | description: | 17 | Status `UP` indicates that the API is running as expected. 18 | 19 | No response or any other response indicates that the API is not functioning correctly. 20 | responses: 21 | "200": 22 | description: Response when service is available 23 | content: 24 | application/json: 25 | schema: 26 | type: object 27 | properties: 28 | status: { type: "string" } 29 | example: { 30 | "status": "UP" 31 | } 32 | /books/lists: 33 | get: 34 | tags: ["books"] 35 | summary: Get a book list 36 | description: | 37 | Returns a list of books. Requires authentication. 38 | 39 | This endpoint uses pagination to handle the returned results.\ 40 | Paginating the results ensures responses are easier to handle.\ 41 | Each response will indicate the total number of results, the \ 42 | current page, and the total number of pages. 43 | parameters: 44 | - name: api-key 45 | description: API Key that is required for this endpoint 46 | in: query 47 | schema: { type: "string" } 48 | required: true 49 | example: "8fhg93xkjd38fhg834jdfgjd" 50 | - name: list 51 | description: "Specifies the list you want to retrieve. Must be one of: favourite-books, non-fiction, wishlist, fiction." 52 | in: query 53 | schema: { type: "string" } 54 | required: true 55 | example: "non-fiction" 56 | - name: page 57 | description: Specifies the page you wish to retrive from the entire result set. 58 | in: query 59 | schema: { type: "integer" } 60 | required: false 61 | example: 1 62 | responses: 63 | "200": 64 | description: Indicates a successful response. 65 | content: 66 | application/json: 67 | schema: 68 | type: object 69 | properties: 70 | status: { type: "string" } 71 | num_results: { type: "integer" } 72 | page: { type: "integer" } 73 | total_pages: { type: "integer" } 74 | results: 75 | type: array 76 | items: 77 | type: object 78 | properties: 79 | title: { type: "string" } 80 | category: { type: "array", items: { type: "string" } } 81 | type: { type: "string" } 82 | author: { type: "string" } 83 | release_year: { type: "integer" } 84 | rating: { oneOf: [{ "type": "string" } , { "type": "number"}] } 85 | example: { 86 | "status": "OK", 87 | "num_results": 17, 88 | "page": 1, 89 | "total_pages": 4, 90 | "results": [ 91 | { 92 | "title": "Crush It!: Why NOW Is the Time to Cash In on Your Passion", 93 | "category": [ 94 | "non-fiction" 95 | ], 96 | "type": "audio", 97 | "author": "Gary Vaynerchuk", 98 | "release_year": 2010, 99 | "rating": "7" 100 | } 101 | ] 102 | } 103 | "400": 104 | description: Indicates that the parameters provided are invalid. 105 | content: 106 | application/json: 107 | schema: 108 | type: object 109 | properties: 110 | error: { type: "string" } 111 | "401": 112 | description: Indicates user is unauthorized 113 | content: 114 | application/json: 115 | schema: 116 | type: object 117 | properties: 118 | error: 119 | type: object 120 | properties: 121 | error-string: { type: "string" } 122 | detail: 123 | type: object 124 | properties: 125 | errorcode: { type: "string" } 126 | "404": 127 | description: Indicates books not found 128 | content: 129 | application/json: 130 | schema: 131 | type: object 132 | properties: 133 | error: { type: "string" } 134 | tags: 135 | - name: status 136 | - name: books -------------------------------------------------------------------------------- /simple-grocery-store-api.md: -------------------------------------------------------------------------------- 1 | # Simple Grocery Store API 2 | 3 | This API allows you to place a grocery order which will be ready for pick-up in the store. 4 | 5 | The API is available at `https://simple-grocery-store-api.click` 6 | 7 | ## Endpoints 8 | 9 | - [Status](#Status) 10 | - [Products](#Products) 11 | - [Get all products](#Get-all-products) 12 | - [Get a product](#Get-a-product) 13 | - [Cart](#Cart) 14 | - [Get a cart](#Get-a-cart) 15 | - [Get cart items](#Get-cart-items) 16 | - [Create a new cart](#Create-a-new-cart) 17 | - [Add an item to cart](#Add-an-item-to-cart) 18 | - [Modify an item in the cart](#Modify-an-item-in-the-cart) 19 | - [Replace an item in the cart](#Replace-an-item-in-the-cart) 20 | - [Delete an item in the cart](#Delete-an-item-in-the-cart) 21 | - [Orders](#Orders) 22 | - [Get all orders](#Get-all-orders) 23 | - [Get a single order](#Get-a-single-order) 24 | - [Create a new order](#Create-a-new-order) 25 | - [Update an order](#Update-an-order) 26 | - [Delete an order](#Delete-an-order) 27 | - [API Authentication](#API-Authentication) 28 | - [Register a new API client](#Register-a-new-API-client) 29 | 30 | ## Status 31 | 32 | **`GET /status`** 33 | 34 | Returns the status of the API. Example response: 35 | 36 | ``` 37 | { 38 | "status": "UP" 39 | } 40 | ``` 41 | 42 | Status `UP` indicates that the API is running as expected. 43 | 44 | No response or any other response indicates that the API is not functioning correctly. 45 | 46 | ## Products 47 | 48 | ### Get all products 49 | 50 | **`GET /products`** 51 | 52 | Returns a list of products from the inventory. 53 | 54 | **Parameters** 55 | 56 | | Name | Type | In | Required | Description | 57 | | ----------- | ------- | ----- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | 58 | | `category` | string | query | No | Specifies the category of products you want to be returned. It can be one of: meat-seafood, fresh-produce, candy, bread-bakery, dairy, eggs, coffee. | 59 | | `results` | integer | query | No | Specifies the number of results you want. Must be number between 1 and 20. By default, only 20 products will be displayed. | 60 | | `available` | boolean | query | No | Specifies the availability of the products. By default, all products will be displayed. | 61 | 62 | **Status codes** 63 | | Status code | Description | 64 | |-----------------|-----------------------------------------------------| 65 | | 200 OK | Indicates a successful response. | 66 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 67 | 68 | Example response: 69 | 70 | ``` 71 | [ 72 | { 73 | "id": 4643, 74 | "category": "coffee", 75 | "name": "Starbucks Coffee Variety Pack, 100% Arabica", 76 | "inStock": true 77 | }, 78 | { 79 | "id": 4646, 80 | "category": "coffee", 81 | "name": "Ethical Bean Medium Dark Roast, Espresso", 82 | "inStock": true 83 | }, 84 | ... 85 | ] 86 | ``` 87 | 88 | ### Get a product 89 | 90 | **`GET /products/:productId`** 91 | 92 | Returns a single product from the inventory. 93 | 94 | **Parameters** 95 | 96 | | Name | Type | In | Required | Description | 97 | | --------------- | ------- | ----- | -------- | ------------------------------------------------ | 98 | | `productId` | integer | path | Yes | Specifies the product's id you wish to retrieve. | 99 | | `product-label` | boolean | query | No | Returns the product label in PDF format. | 100 | 101 | **Status codes** 102 | 103 | | Status code | Description | 104 | | ------------- | --------------------------------------------------------- | 105 | | 200 OK | Indicates a successful response. | 106 | | 404 Not found | Indicates that there is no product with the specified id. | 107 | 108 | ## Cart 109 | 110 | ### Get a cart 111 | 112 | **`GET /carts/:cartId`** 113 | 114 | Returns a cart. 115 | 116 | **Parameters** 117 | 118 | | Name | Type | In | Required | Description | 119 | | -------- | ------ | ---- | -------- | -------------------------------------------------- | 120 | | `cartId` | string | path | Yes | Specifies the id of the cart you wish to retrieve. | 121 | 122 | **Status codes** 123 | 124 | | Status code | Description | 125 | | ------------- | ------------------------------------------------------ | 126 | | 200 OK | Indicates a successful response. | 127 | | 404 Not found | Indicates that there is no cart with the specified id. | 128 | 129 | ### Get cart items 130 | 131 | Returns the items in a cart. 132 | 133 | **`GET /carts/:cartId/items`** 134 | 135 | **Parameters** 136 | 137 | | Name | Type | In | Required | Description | 138 | | -------- | ------ | ---- | -------- | ---------------------------------------------------------------------- | 139 | | `cartId` | string | path | Yes | Specifies the id of the cart for which you wish to retrieve the items. | 140 | 141 | **Status codes** 142 | 143 | | Status code | Description | 144 | | ------------- | ------------------------------------------------------ | 145 | | 200 OK | Indicates a successful response. | 146 | | 404 Not found | Indicates that there is no cart with the specified id. | 147 | 148 | ### Create a new cart 149 | 150 | To create a new cart, submit an empty POST request to the `/carts` endpoint. 151 | 152 | **`POST /carts`** 153 | 154 | Creates a new cart and returns the id in the response body. 155 | 156 | **Parameters** 157 | 158 | No parameters are accepted for this request. 159 | 160 | **Status codes** 161 | 162 | | Status code | Description | 163 | | ----------- | ------------------------------------------------------ | 164 | | 201 Created | Indicates that the cart has been created successfully. | 165 | 166 | Example response body: 167 | 168 | ``` 169 | { 170 | "created": true, 171 | "cartId": "bx0-ycNjqIm5IvufuuZ09" 172 | } 173 | ``` 174 | 175 | ### Add an item to cart 176 | 177 | Allows the addition of items to an existing cart. Only one item can be added at a time. 178 | 179 | **`POST /carts/:cartId/items`** 180 | 181 | The request body needs to be in JSON format. 182 | 183 | **Parameters** 184 | 185 | | Name | Type | In | Required | Description | 186 | | ----------- | ------- | ---- | -------- | --------------------------------------------------- | 187 | | `cartId` | string | path | Yes | Specifies the cart id. | 188 | | `productId` | integer | body | Yes | Specifies the product id | 189 | | `quantity` | integer | body | No | If no quantity is provided, the default value is 1. | 190 | 191 | Example request body: 192 | 193 | ``` 194 | { 195 | "productId": 1234 196 | } 197 | ``` 198 | 199 | **Status codes** 200 | 201 | | Status code | Description | 202 | | --------------- | ---------------------------------------------------- | 203 | | 201 Created | Indicates that the item has been added successfully. | 204 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 205 | 206 | ### Modify an item in the cart 207 | 208 | Allows modifying information about an item in the cart. 209 | 210 | **`PATCH /carts/:cartId/items/:itemId`** 211 | 212 | The request body needs to be in JSON format. 213 | 214 | **Parameters** 215 | 216 | | Name | Type | In | Required | Description | 217 | | ---------- | ------- | ---- | -------- | ---------------------- | 218 | | `cartId` | string | path | Yes | Specifies the cart id. | 219 | | `itemId` | string | path | Yes | Specifies the item id. | 220 | | `quantity` | integer | body | Yes | Quantity | 221 | 222 | **Status codes** 223 | 224 | | Status code | Description | 225 | | --------------- | -------------------------------------------------------------- | 226 | | 204 No Content | Indicates that the item has been updated successfully. | 227 | | 400 Bad Request | Indicates that the parameters provided are invalid or missing. | 228 | | 404 Not found | The cart or the item could not be found. | 229 | 230 | ### Replace an item in the cart 231 | 232 | Replace an item in the cart. 233 | 234 | **`PUT /carts/:cartId/items/:itemId`** 235 | 236 | The request body needs to be in JSON format. 237 | 238 | **Parameters** 239 | 240 | | Name | Type | In | Required | Description | 241 | | ----------- | ------- | ---- | -------- | ------------------------- | 242 | | `cartId` | string | path | Yes | Specifies the cart id. | 243 | | `itemId` | string | path | Yes | Specifies the item id. | 244 | | `productId` | integer | body | Yes | Specifies the product id. | 245 | | `quantity` | integer | body | No | Quantity | 246 | 247 | **Status codes** 248 | 249 | | Status code | Description | 250 | | --------------- | -------------------------------------------------------------- | 251 | | 204 No Content | Indicates that the item has been updated successfully. | 252 | | 400 Bad Request | Indicates that the parameters provided are invalid or missing. | 253 | | 404 Not found | The cart or the item could not be found. | 254 | 255 | ### Delete an item in the cart 256 | 257 | Deletes an item in the cart. 258 | 259 | **`DELETE /carts/:cartId/items/:itemId`** 260 | 261 | **Parameters** 262 | 263 | | Name | Type | In | Required | Description | 264 | | ----------- | ------ | ---- | -------- | ----------------------- | 265 | | `cartId` | string | path | Yes | Specifies the cart id. | 266 | | `itemId` | string | path | Yes | Specifies the item id. | 267 | 268 | **Status codes** 269 | 270 | | Status code | Description | 271 | | -------------- | ------------------------------------------------------ | 272 | | 204 No Content | Indicates that the item has been deleted successfully. | 273 | | 404 Not found | The cart or the item could not be found. | 274 | 275 | ## Orders 276 | 277 | ### Get all orders 278 | 279 | Returns all orders created by the API client. 280 | 281 | **`GET /orders`** 282 | 283 | **Parameters** 284 | 285 | | Name | Type | In | Required | Description | 286 | | --------------- | ------ | ------ | -------- | --------------------------------------------- | 287 | | `Authorization` | string | header | Yes | Specifies the bearer token of the API client. | 288 | 289 | **Status codes** 290 | 291 | | Status code | Description | 292 | | ---------------- | ------------------------------------------------------------------------------------------------------ | 293 | | 200 OK | Indicates a successful response. | 294 | | 401 Unauthorized | Indicates that the request has not been authenticated. Check the response body for additional details. | 295 | 296 | ### Get a single order 297 | 298 | Returns a single order. 299 | 300 | **`GET /orders/:orderId`** 301 | 302 | **Parameters** 303 | 304 | | Name | Type | In | Required | Description | 305 | | --------------- | ------- | ------ | -------- | ----------------------------------- | 306 | | `Authorization` | string | header | Yes | The bearer token of the API client. | 307 | | `orderId` | string | path | Yes | The order id. | 308 | | `invoice` | boolean | query | No | Show the PDF invoice. | 309 | 310 | **Status codes** 311 | 312 | | Status code | Description | 313 | | ---------------- | ------------------------------------------------------------------------------------------------------ | 314 | | 200 OK | Indicates a successful response. | 315 | | 401 Unauthorized | Indicates that the request has not been authenticated. Check the response body for additional details. | 316 | | 404 Not found | Indicates that there is no order with the specified id associated with the API client. | 317 | 318 | ### Create a new order 319 | 320 | **`POST /orders`** 321 | 322 | The request body needs to be in JSON format. 323 | Once the order has been successfully submitted, the cart is deleted. 324 | 325 | **Parameters** 326 | 327 | | Name | Type | In | Required | Description | 328 | | --------------- | ------ | ------ | -------- | ------------------------------------ | 329 | | `Authorization` | string | header | Yes | The bearer token of the API client. | 330 | | `cartId` | string | body | Yes | The cart id | 331 | | `customerName` | string | body | Yes | The name of the customer. | 332 | | `comment` | string | body | No | A comment associated with the order. | 333 | 334 | Example request body: 335 | 336 | ``` 337 | { 338 | "cartId": "ZFe4yhG5qNhmuNyrbLWa4", 339 | "customerName": "John Doe" 340 | } 341 | ``` 342 | 343 | **Status codes** 344 | 345 | | Status code | Description | 346 | | ---------------- | ------------------------------------------------------------------------------------------------------ | 347 | | 201 Created | Indicates that the order has been created successfully. | 348 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 349 | | 401 Unauthorized | Indicates that the request has not been authenticated. Check the response body for additional details. | 350 | 351 | ### Update an order 352 | 353 | **`PATCH /orders/:orderId`** 354 | 355 | The request body needs to be in JSON format. 356 | 357 | **Parameters** 358 | 359 | | Name | Type | In | Required | Description | 360 | | --------------- | ------ | ------ | -------- | ------------------------------------ | 361 | | `Authorization` | string | header | Yes | The bearer token of the API client. | 362 | | `orderId` | string | path | Yes | The order id. | 363 | | `customerName` | string | body | No | The name of the customer. | 364 | | `comment` | string | body | No | A comment associated with the order. | 365 | 366 | **Status codes** 367 | 368 | | Status code | Description | 369 | | ---------------- | ------------------------------------------------------------------------------------------------------ | 370 | | 204 No Content | Indicates that the order has been updated successfully. | 371 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 372 | | 401 Unauthorized | Indicates that the request has not been authenticated. Check the response body for additional details. | 373 | | 404 Not found | Indicates that there is no order with the specified id associated with the API client. | 374 | 375 | Example request body: 376 | 377 | ``` 378 | { 379 | "customerName": "Joe Doe" 380 | } 381 | ``` 382 | 383 | ### Delete an order 384 | 385 | **`DELETE /orders/:orderId`** 386 | 387 | **Parameters** 388 | 389 | | Name | Type | In | Required | Description | 390 | | --------------- | ------ | ------ | -------- | ----------------------------------- | 391 | | `Authorization` | string | header | Yes | The bearer token of the API client. | 392 | | `orderId` | string | path | Yes | The order id. | 393 | 394 | **Status codes** 395 | 396 | | Status code | Description | 397 | | ---------------- | ------------------------------------------------------------------------------------------------------ | 398 | | 204 No Content | Indicates that the order has been deleted successfully. | 399 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 400 | | 401 Unauthorized | Indicates that the request has not been authenticated. Check the response body for additional details. | 401 | | 404 Not found | Indicates that there is no order with the specified id associated with the API client. | 402 | 403 | ## API Authentication 404 | 405 | Some endpoints may require authentication. To submit or view an order, you need to register your API client and obtain an access token. 406 | 407 | The endpoints that require authentication expect a bearer token sent in the `Authorization` header. 408 | 409 | Example: 410 | 411 | `Authorization: Bearer YOUR TOKEN` 412 | 413 | ### Register a new API client 414 | 415 | **`POST /api-clients`** 416 | 417 | **Parameters** 418 | 419 | The request body needs to be in JSON format. 420 | 421 | | Name | Type | In | Required | Description | 422 | | ------------- | ------ | ---- | -------- | -------------------------------------- | 423 | | `clientName` | string | body | Yes | The name of the API client. | 424 | | `clientEmail` | string | body | Yes | The email address of the API client. * | 425 | 426 | 427 | * The email address DOES NOT need to be real. The email will not be stored on the server. 428 | 429 | **Status codes** 430 | 431 | | Status code | Description | 432 | |-----------------|-----------------------------------------------------------------------------------| 433 | | 201 Created | Indicates that the client has been registered successfully. | 434 | | 400 Bad Request | Indicates that the parameters provided are invalid. | 435 | | 409 Conflict | Indicates that an API client has already been registered with this email address. | 436 | 437 | Example request body: 438 | 439 | ``` 440 | { 441 | "clientName": "Postman on Valentin's computer", 442 | "clientEmail": "valentin@example.com" 443 | } 444 | ``` 445 | 446 | The response body will contain the access token. 447 | -------------------------------------------------------------------------------- /simple-grocery-store-openapi.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.3 2 | info: 3 | title: Grocery Store API (Open API Spec) 4 | description: | 5 | This API allows you to place a grocery order which will be ready for pick-up in the store. The API is available at https://simple-grocery-store-api.click 6 | A fuller description is located at (Simple Grocery Store API)[https://github.com/vdespa/Postman-Complete-Guide-API-Testing/blob/main/simple-grocery-store-api.md] 7 | version: 1.1.0 8 | servers: 9 | - url: https://simple-grocery-store-api.click 10 | paths: 11 | /status: 12 | get: 13 | tags: ["status"] 14 | summary: Returns the status of the API 15 | description: | 16 | Status UP indicates that the API is running as expected. 17 | No response or any other response indicates that the API is not functioning correctly. 18 | responses: 19 | '200': 20 | description: Status is UP 21 | content: 22 | application/json: 23 | schema: 24 | type: object 25 | properties: 26 | status: 27 | type: string 28 | required: ['status'] 29 | example: { 30 | "status": "UP" 31 | } 32 | /products: 33 | get: 34 | tags: ["product"] 35 | summary: Get all products 36 | description: Returns a list of products from the inventory. 37 | parameters: 38 | - name: category 39 | description: "Specifies the category of products you want to be returned. It can be one of: meat-seafood, fresh-produce, candy, bread-bakery, dairy, eggs, coffee." 40 | in: query 41 | schema: { type: "string" } 42 | required: false 43 | example: "dairy" 44 | - name: results 45 | description: "Specifies the number of results you want. Must be number between 1 and 20. By default, only 20 products will be displayed." 46 | in: query 47 | schema: 48 | type: "integer" 49 | minimum: 1 50 | maximum: 20 51 | required: false 52 | example: 20 53 | - name: available 54 | description: "Specifies the availability of the products. By default, all products will be displayed." 55 | in: query 56 | schema: { type: boolean } 57 | required: false 58 | example: false 59 | responses: 60 | "200": 61 | description: Successful response 62 | content: 63 | application/json: 64 | schema: 65 | type: array 66 | items: 67 | type: object 68 | properties: 69 | id: { type: "number" } 70 | category: { type: "string" } 71 | name: { type: "string" } 72 | inStock: { type: "boolean" } 73 | example: [ 74 | { 75 | "id": 4643, 76 | "category": "coffee", 77 | "name": "Starbucks Coffee Variety Pack, 100% Arabica", 78 | "inStock": true 79 | }, 80 | { 81 | "id": 4646, 82 | "category": "coffee", 83 | "name": "Ethical Bean Medium Dark Roast, Espresso", 84 | "inStock": true 85 | }, 86 | ] 87 | /products/{productId}: 88 | get: 89 | tags: ["product"] 90 | summary: Get a product 91 | description: Returns a single product from the inventory. 92 | parameters: 93 | - name: productId 94 | description: Specifies the product's id you wish to retrieve. 95 | in: path 96 | schema: { type: "integer" } 97 | required: true 98 | example: 4643 99 | - name: product-label 100 | description: Returns the product label in PDF format. 101 | in: query 102 | schema: { type: boolean } 103 | required: false 104 | example: true 105 | responses: 106 | "200": 107 | description: Indicates successful response 108 | content: 109 | application/json: 110 | schema: 111 | type: object 112 | properties: 113 | id: { type: "integer" } 114 | category: { type: "string" } 115 | name: { type: "string" } 116 | manufacturer: { type: "string" } 117 | price: { type: "number" } 118 | "current-stock": { type: "number" } 119 | inStock: { type: "boolean" } 120 | example: { 121 | "id": 4643, 122 | "category": "coffee", 123 | "name": "Starbucks Coffee Variety Pack, 100% Arabica", 124 | "manufacturer": "Starbucks", 125 | "price": 40.91, 126 | "current-stock": 14, 127 | "inStock": true 128 | } 129 | "404": { "$ref": "#/components/responses/404Response" } 130 | /carts: 131 | post: 132 | tags: ["cart"] 133 | summary: Create a new cart 134 | description: To create a new cart, submit an empty POST request to the /carts endpoint. 135 | responses: 136 | "201": 137 | description: Indicates that the cart has been created successfully. 138 | content: 139 | application/json: 140 | schema: 141 | type: object 142 | properties: 143 | created: { "type": "boolean" } 144 | cartId: { "type": "string" } 145 | example: { 146 | "created": true, 147 | "cartId": "bx0-ycNjqIm5IvufuuZ09" 148 | } 149 | /carts/{cartId}: 150 | parameters: 151 | - { "$ref": "#/components/parameters/cartId"} 152 | get: 153 | tags: ["cart"] 154 | description: Get a cart 155 | summary: Returns a cart 156 | responses: 157 | "200": 158 | description: Indicates successful response 159 | content: 160 | application/json: 161 | schema: 162 | type: object 163 | properties: 164 | created: 165 | type: string 166 | format: date-time 167 | items: 168 | type: array 169 | items: { "$ref": "#/components/schemas/cartItem" } 170 | "404": { "$ref": "#/components/responses/404Response" } 171 | /carts/{cartId}/items: 172 | parameters: 173 | - { "$ref": "#/components/parameters/cartId" } 174 | get: 175 | tags: ["cart"] 176 | summary: Get cart items 177 | description: Returns the items in a cart. 178 | responses: 179 | "200": 180 | description: Indicates a successful response. 181 | content: 182 | application/json: 183 | schema: 184 | type: array 185 | items: { "$ref": "#/components/schemas/cartItem" } 186 | "404": { "$ref": "#/components/responses/404Response" } 187 | post: 188 | tags: ["cart"] 189 | summary: Add an item to cart 190 | description: Allows the addition of items to an existing cart. Only one item can be added at a time. 191 | requestBody: 192 | content: 193 | application/json: 194 | schema: 195 | type: object 196 | properties: 197 | productId: 198 | description: Specifies the product id. 199 | type: integer 200 | quantity: 201 | description: If no quantity is provided, the default value is 1 202 | default: 1 203 | required: ["productId"] 204 | example: { 205 | "productId": 4643 206 | } 207 | responses: 208 | "201": 209 | description: Indicates that the item has been added successfully. 210 | content: 211 | application/json: 212 | schema: 213 | type: object 214 | properties: 215 | created: { "type": "boolean"} 216 | itemId: { "type": "string" } 217 | example: { 218 | "created": true, 219 | "itemId": "307737708" 220 | } 221 | "400": { "$ref": "#/components/responses/400Response" } 222 | /carts/{cartId}/items/{itemId}: 223 | parameters: 224 | - { "$ref": "#/components/parameters/cartId" } 225 | - { "$ref": "#/components/parameters/itemId" } 226 | patch: 227 | tags: ["cart"] 228 | summary: Allows modifying information about an item in the cart. 229 | description: The request body needs to be in JSON format. 230 | requestBody: 231 | content: 232 | application/json: 233 | schema: 234 | type: object 235 | properties: 236 | quantity: { "type": "integer" } 237 | required: ["quantity"] 238 | example: { 239 | quantity: 1 240 | } 241 | responses: 242 | "204": 243 | description: Indicates that the item has been updated successfully. 244 | "400": { "$ref": "#/components/responses/400Response" } 245 | "404": { "$ref": "#/components/responses/404Response" } 246 | put: 247 | tags: ["cart"] 248 | summary: Replace an item in the cart. 249 | description: The request body needs to be in JSON format. 250 | requestBody: 251 | content: 252 | application/json: 253 | schema: 254 | type: object 255 | properties: 256 | productId: { "type": "integer" } 257 | quantity: { "type": "integer" } 258 | required: ["productId"] 259 | example: { 260 | "productId": 4643, 261 | "quantity": 1 262 | } 263 | responses: 264 | "204": 265 | description: Indicates that the item has been updated successfully. 266 | "400": { "$ref": "#/components/responses/400Response" } 267 | "404": { "$ref": "#/components/responses/404Response" } 268 | delete: 269 | tags: ["cart"] 270 | summary: Deletes an item in the cart. 271 | responses: 272 | "204": 273 | description: Indicates that the item has been deleted successfully. 274 | "404": { "$ref": "#/components/responses/404Response" } 275 | /orders: 276 | parameters: 277 | - { "$ref": "#/components/parameters/authorization" } 278 | get: 279 | tags: ["order"] 280 | summary: Get all /orders 281 | description: Returns all orders created by the API client 282 | responses: 283 | "200": 284 | description: Indicates a successful response. 285 | content: 286 | application/json: 287 | schema: 288 | type: array 289 | items: { "$ref": "#/components/schemas/order" } 290 | "401": { "$ref": "#/components/responses/401Response" } 291 | post: 292 | tags: ["order"] 293 | summary: Create a new order 294 | description: The request body needs to be in JSON format. Once the order has been successfully submitted, the cart is deleted. 295 | requestBody: 296 | content: 297 | application/json: 298 | schema: 299 | type: object 300 | properties: 301 | cartId: { type: "string" } 302 | customerName: { type: "string" } 303 | comment: { type: "string" } 304 | required: ["cartId","customerName"] 305 | example: { 306 | "cartId": "ZFe4yhG5qNhmuNyrbLWa4", 307 | "customerName": "John Doe" 308 | } 309 | responses: 310 | "201": 311 | description: Indicates that the order has been created successfully. 312 | content: 313 | application/json: 314 | schema: 315 | type: object 316 | properties: 317 | created: { "type": "boolean" } 318 | orderId: { "type": "string" } 319 | example: { 320 | "created": true, 321 | "orderId": "vJln6UPMuNEtn4x3UmfWC" 322 | } 323 | "400": { "$ref": "#/components/responses/400Response" } 324 | "401": { "$ref": "#/components/responses/401Response" } 325 | /orders/{orderId}: 326 | parameters: 327 | - { "$ref": "#/components/parameters/authorization" } 328 | - { "$ref": "#/components/parameters/orderId"} 329 | patch: 330 | tags: ["order"] 331 | summary: Updates the comment or customer name associated with an order 332 | description: The request body needs to be in JSON format. 333 | requestBody: 334 | content: 335 | application/json: 336 | schema: 337 | type: object 338 | properties: 339 | customerName: { type: "string" } 340 | comment: { type: "string" } 341 | example: { 342 | "customerName": "John Doe", 343 | "comment": "An example comment" 344 | } 345 | responses: 346 | "204": 347 | description: Indicates that the order has been updated successfully. 348 | "400": { "$ref": "#/components/responses/400Response" } 349 | "401": { "$ref": "#/components/responses/401Response" } 350 | "404": { "$ref": "#/components/responses/404Response" } 351 | delete: 352 | tags: ["order"] 353 | summary: Delete an order 354 | responses: 355 | "204": 356 | description: Indicates that the order has been successfully deleted. 357 | "400": { "$ref": "#/components/responses/400Response" } 358 | "401": { "$ref": "#/components/responses/401Response" } 359 | "404": { "$ref": "#/components/responses/404Response" } 360 | /api-clients: 361 | description: | 362 | Some endpoints may require authentication. To submit or view an order, you need to register your API client and obtain an access token. 363 | 364 | The endpoints that require authentication expect a bearer token sent in the Authorization header. 365 | 366 | Example: 367 | 368 | Authorization: Bearer YOUR TOKEN 369 | post: 370 | tags: ["authentication"] 371 | summary: Register a new API client 372 | requestBody: 373 | content: 374 | application/json: 375 | schema: 376 | type: object 377 | properties: 378 | clientName: { "type": "string", "description": "The name of the API client." } 379 | clientEmail: { "type": "string", "description": "The email address of the API client. The email address DOES NOT need to be real. The email will not be stored on the server." } 380 | required: ["clientName","clientEmail"] 381 | example: { 382 | clientName: "John Doe", 383 | clientEmail: "150b3447-7d12-426e-ba77-a1203d28f8a5@example.com" 384 | } 385 | responses: 386 | "201": 387 | description: Indicates that the client has been registered successfully. 388 | content: 389 | application/json: 390 | schema: 391 | type: object 392 | properties: 393 | accessToken: { "type": "string" } 394 | example: { 395 | "accessToken": "8363b83fa762c34055b7d8135e2c521fc9fa5b743b140e05ca178b62a21ba9f2" 396 | } 397 | "400": { "$ref": "#/components/responses/400Response" } 398 | "409": 399 | description: Indicates that an API client has already been registered with this email address. 400 | content: 401 | application/json: 402 | schema: { "$ref": "#/components/schemas/error" } 403 | security: 404 | - {} 405 | - bearer: [] 406 | components: 407 | schemas: 408 | order: 409 | type: object 410 | properties: 411 | id: { "type": "string" } 412 | items: { "$ref": "#/components/schemas/cartItem" } 413 | customerName: { "type": "string" } 414 | created: { "type": "string", format: "date-time" } 415 | comment: { "type": "string" } 416 | example: { 417 | "id": "vJln6UPMuNEtn4x3UmfWC", 418 | "items": [ 419 | { 420 | "id": 97962858, 421 | "productId": 4643, 422 | "quantity": 1 423 | } 424 | ], 425 | "customerName": "Postman on Valentin's computer", 426 | "created": "2024-07-19T12:13:24.934Z", 427 | "comment": "" 428 | } 429 | error: 430 | type: object 431 | properties: 432 | error: { type: "string" } 433 | required: ["error"] 434 | example: { 435 | "error": "The error message associated with the request" 436 | } 437 | cartItem: 438 | type: object 439 | properties: 440 | id: { type: "string" } 441 | productId: { type: "integer" } 442 | quantity: { type: "integer" } 443 | required: ["id","productId","quantity"] 444 | example: { 445 | "id": 453651364, 446 | "productId": 4646, 447 | "quantity": 1 448 | } 449 | parameters: 450 | cartId: 451 | name: cartId 452 | description: Specifies the id of the cart 453 | in: path 454 | schema: { type: "string" } 455 | required: true 456 | example: "xrc_kqazYgEQyTvTLX1hk" 457 | itemId: 458 | name: itemId 459 | description: Specifies the id of the item 460 | in: path 461 | schema: { type: "string" } 462 | required: true 463 | example: "383044229" 464 | orderId: 465 | name: orderId 466 | description: Specifies the id of the order 467 | in: path 468 | schema: { type: "string" } 469 | required: true 470 | authorization: 471 | name: Authorization 472 | description: The bearer token of the API client. 473 | in: header 474 | schema: { type: "string" } 475 | required: true 476 | example: "150b3447-7d12-426e-ba77-a1203d28f8a5@example.com" 477 | responses: 478 | 401Response: 479 | description: Indicates that the request has not been authenticated. Check the response body for additional details. 480 | content: 481 | application/json: 482 | schema: { "$ref": "#/components/schemas/error" } 483 | 404Response: 484 | description: Indicates that there is no entity with the specified id associated with the API client. 485 | content: 486 | application/json: 487 | schema: { "$ref": "#/components/schemas/error" } 488 | 400Response: 489 | description: Indicates that the parameters provided are invalid. 490 | content: 491 | application/json: 492 | schema: { "$ref": "#/components/schemas/error" } 493 | securitySchemes: 494 | bearer: 495 | type: http 496 | scheme: bearer 497 | description: Use /api-clients endpoint to get token 498 | tags: 499 | - name: status 500 | - name: product 501 | - name: cart 502 | - name: order 503 | - name: authentication 504 | --------------------------------------------------------------------------------