{ "openapi": "3.0.3", "info": { "title": "Grocery Store API (Open API Spec)", "description": "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.glitch.me\nA 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]\n", "version": "1.1.0" }, "servers": [ { "url": "https://simple-grocery-store-api.glitch.me" } ], "paths": { "/status": { "get": { "tags": [ "status" ], "summary": "Returns the status of the API", "description": "Status UP indicates that the API is running as expected.\nNo response or any other response indicates that the API is not functioning correctly.\n", "responses": { "200": { "description": "Status is UP", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "example": { "status": "UP" } } } } } } }, "/products": { "get": { "tags": [ "product" ], "summary": "Get all products", "description": "Returns a list of products from the inventory.", "parameters": [ { "name": "category", "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.", "in": "query", "schema": { "type": "string" }, "required": false, "example": "dairy" }, { "name": "results", "description": "Specifies the number of results you want. Must be number between 1 and 20. By default, only 20 products will be displayed.", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "required": false, "example": 20 }, { "name": "available", "description": "Specifies the availability of the products. By default, all products will be displayed.", "in": "query", "schema": { "type": "boolean" }, "required": false, "example": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "category": { "type": "string" }, "name": { "type": "string" }, "inStock": { "type": "boolean" } } } }, "example": [ { "id": 4643, "category": "coffee", "name": "Starbucks Coffee Variety Pack, 100% Arabica", "inStock": true }, { "id": 4646, "category": "coffee", "name": "Ethical Bean Medium Dark Roast, Espresso", "inStock": true } ] } } } } } }, "/products/{productId}": { "get": { "tags": [ "product" ], "summary": "Get a product", "description": "Returns a single product from the inventory.", "parameters": [ { "name": "productId", "description": "Specifies the product's id you wish to retrieve.", "in": "path", "schema": { "type": "integer" }, "required": true, "example": 4643 }, { "name": "product-label", "description": "Returns the product label in PDF format.", "in": "query", "schema": { "type": "boolean" }, "required": false, "example": true } ], "responses": { "200": { "description": "Indicates successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "category": { "type": "string" }, "name": { "type": "string" }, "manufacturer": { "type": "string" }, "price": { "type": "number" }, "current-stock": { "type": "number" }, "inStock": { "type": "boolean" } } }, "example": { "id": 4643, "category": "coffee", "name": "Starbucks Coffee Variety Pack, 100% Arabica", "manufacturer": "Starbucks", "price": 40.91, "current-stock": 14, "inStock": true } } } }, "404": { "$ref": "#/components/responses/404Response" } } } }, "/carts": { "post": { "tags": [ "cart" ], "summary": "Create a new cart", "description": "To create a new cart, submit an empty POST request to the /carts endpoint.", "responses": { "201": { "description": "Indicates that the cart has been created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "boolean" }, "cartId": { "type": "string" } } }, "example": { "created": true, "cartId": "bx0-ycNjqIm5IvufuuZ09" } } } } } } }, "/carts/{cartId}": { "parameters": [ { "$ref": "#/components/parameters/cartId" } ], "get": { "tags": [ "cart" ], "description": "Get a cart", "summary": "Returns a cart", "responses": { "200": { "description": "Indicates successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/cartItem" } } } } } } }, "404": { "$ref": "#/components/responses/404Response" } } } }, "/carts/{cartId}/items": { "parameters": [ { "$ref": "#/components/parameters/cartId" } ], "get": { "tags": [ "cart" ], "summary": "Get cart items", "description": "Returns the items in a cart.", "responses": { "200": { "description": "Indicates a successful response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/cartItem" } } } } }, "404": { "$ref": "#/components/responses/404Response" } } }, "post": { "tags": [ "cart" ], "summary": "Add an item to cart", "description": "Allows the addition of items to an existing cart. Only one item can be added at a time.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "description": "Specifies the product id.", "type": "integer" }, "quantity": { "description": "If no quantity is provided, the default value is 1", "default": 1 } }, "required": [ "productId" ] }, "example": { "productId": 4643 } } } }, "responses": { "201": { "description": "Indicates that the item has been added successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "boolean" }, "itemId": { "type": "string" } } }, "example": { "created": true, "itemId": "307737708" } } } }, "400": { "$ref": "#/components/responses/400Response" } } } }, "/carts/{cartId}/items/{itemId}": { "parameters": [ { "$ref": "#/components/parameters/cartId" }, { "$ref": "#/components/parameters/itemId" } ], "patch": { "tags": [ "cart" ], "summary": "Allows modifying information about an item in the cart.", "description": "The request body needs to be in JSON format.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer" } }, "required": [ "quantity" ] }, "example": { "quantity": 1 } } } }, "responses": { "204": { "description": "Indicates that the item has been updated successfully." }, "400": { "$ref": "#/components/responses/400Response" }, "404": { "$ref": "#/components/responses/404Response" } } }, "put": { "tags": [ "cart" ], "summary": "Replace an item in the cart.", "description": "The request body needs to be in JSON format.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer" }, "quantity": { "type": "integer" } }, "required": [ "productId" ] }, "example": { "productId": 4643, "quantity": 1 } } } }, "responses": { "204": { "description": "Indicates that the item has been updated successfully." }, "400": { "$ref": "#/components/responses/400Response" }, "404": { "$ref": "#/components/responses/404Response" } } }, "delete": { "tags": [ "cart" ], "summary": "Deletes an item in the cart.", "responses": { "204": { "description": "Indicates that the item has been deleted successfully." }, "404": { "$ref": "#/components/responses/404Response" } } } }, "/orders": { "parameters": [ { "$ref": "#/components/parameters/authorization" } ], "get": { "tags": [ "order" ], "summary": "Get all /orders", "description": "Returns all orders created by the API client", "responses": { "200": { "description": "Indicates a successful response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/order" } } } } }, "401": { "$ref": "#/components/responses/401Response" } } }, "post": { "tags": [ "order" ], "summary": "Create a new order", "description": "The request body needs to be in JSON format. Once the order has been successfully submitted, the cart is deleted.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cartId": { "type": "string" }, "customerName": { "type": "string" }, "comment": { "type": "string" } }, "required": [ "cartId", "customerName" ] }, "example": { "cartId": "ZFe4yhG5qNhmuNyrbLWa4", "customerName": "John Doe" } } } }, "responses": { "201": { "description": "Indicates that the order has been created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "boolean" }, "orderId": { "type": "string" } } }, "example": { "created": true, "orderId": "vJln6UPMuNEtn4x3UmfWC" } } } }, "400": { "$ref": "#/components/responses/400Response" }, "401": { "$ref": "#/components/responses/401Response" } } } }, "/orders/{orderId}": { "parameters": [ { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/orderId" } ], "patch": { "tags": [ "order" ], "summary": "Updates the comment or customer name associated with an order", "description": "The request body needs to be in JSON format.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerName": { "type": "string" }, "comment": { "type": "string" } } }, "example": { "customerName": "John Doe", "comment": "An example comment" } } } }, "responses": { "204": { "description": "Indicates that the order has been updated successfully." }, "400": { "$ref": "#/components/responses/400Response" }, "401": { "$ref": "#/components/responses/401Response" }, "404": { "$ref": "#/components/responses/404Response" } } }, "delete": { "tags": [ "order" ], "summary": "Delete an order", "responses": { "204": { "description": "Indicates that the order has been successfully deleted." }, "400": { "$ref": "#/components/responses/400Response" }, "401": { "$ref": "#/components/responses/401Response" }, "404": { "$ref": "#/components/responses/404Response" } } } }, "/api-clients": { "description": "Some endpoints may require authentication. To submit or view an order, you need to register your API client and obtain an access token.\n\nThe endpoints that require authentication expect a bearer token sent in the Authorization header.\n\nExample:\n\nAuthorization: Bearer YOUR TOKEN\n", "post": { "tags": [ "authentication" ], "summary": "Register a new API client", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "clientName": { "type": "string", "description": "The name of the API client." }, "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." } }, "required": [ "clientName", "clientEmail" ] }, "example": { "clientName": "John Doe", "clientEmail": "150b3447-7d12-426e-ba77-a1203d28f8a5@example.com" } } } }, "responses": { "201": { "description": "Indicates that the client has been registered successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" } } }, "example": { "accessToken": "8363b83fa762c34055b7d8135e2c521fc9fa5b743b140e05ca178b62a21ba9f2" } } } }, "400": { "$ref": "#/components/responses/400Response" }, "409": { "description": "Indicates that an API client has already been registered with this email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } } }, "security": [ {}, { "bearer": [] } ], "components": { "schemas": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "items": { "$ref": "#/components/schemas/cartItem" }, "customerName": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } }, "example": { "id": "vJln6UPMuNEtn4x3UmfWC", "items": [ { "id": 97962858, "productId": 4643, "quantity": 1 } ], "customerName": "Postman on Valentin's computer", "created": "2024-07-19T12:13:24.934Z", "comment": "" } }, "error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "example": { "error": "The error message associated with the request" } }, "cartItem": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer" }, "quantity": { "type": "integer" } }, "required": [ "id", "productId", "quantity" ], "example": { "id": 453651364, "productId": 4646, "quantity": 1 } } }, "parameters": { "cartId": { "name": "cartId", "description": "Specifies the id of the cart", "in": "path", "schema": { "type": "string" }, "required": true, "example": "xrc_kqazYgEQyTvTLX1hk" }, "itemId": { "name": "itemId", "description": "Specifies the id of the item", "in": "path", "schema": { "type": "string" }, "required": true, "example": "383044229" }, "orderId": { "name": "orderId", "description": "Specifies the id of the order", "in": "path", "schema": { "type": "string" }, "required": true }, "authorization": { "name": "Authorization", "description": "The bearer token of the API client.", "in": "header", "schema": { "type": "string" }, "required": true, "example": "150b3447-7d12-426e-ba77-a1203d28f8a5@example.com" } }, "responses": { "401Response": { "description": "Indicates that the request has not been authenticated. Check the response body for additional details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "404Response": { "description": "Indicates that there is no entity with the specified id associated with the API client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "400Response": { "description": "Indicates that the parameters provided are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Use /api-clients endpoint to get token" } } }, "tags": [ { "name": "status" }, { "name": "product" }, { "name": "cart" }, { "name": "order" }, { "name": "authentication" } ] }