product operations
openapi: 3.1.0
info:
title: Princess Beef Heavy Industries pb33f Giftshop Product API
summary: 'We sell t-shirts, hoodies and other merchandise for pb33f.
'
description: 'Want some cool gear, to go with your cool code? We''ve got you covered. Buy a t-shirt, hoodie or other merchandise from our store to show your support for pb33f.
'
version: 0.0.1
contact:
url: https://pb33f.io/company
name: Dave Shanley
email: buckaroo@pb33f.io
license:
name: GPL-3.0
url: https://www.gnu.org/licenses/gpl-3.0.en.html
servers:
- url: https://api.pb33f.io/wiretap/giftshop
description: Live production endpoint for general use.
tags:
- name: Product
description: product operations
paths:
/products:
post:
security:
- ApiKeyAuth:
- write:products
tags:
- Product
operationId: createProduct
description: 'Create a new product. If the product already exists, or the data is invalid a 400 error will be returned.
'
summary: Princess Beef Heavy Industries Create a new product.
requestBody:
description: The new product to create.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
examples:
newProduct:
$ref: '#/components/examples/NewProductExample'
responses:
'200':
$ref: '#/components/responses/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/ServerError'
'500':
$ref: '#/components/responses/ServerError'
get:
security:
- {}
parameters:
- $ref: '#/components/parameters/Category'
tags:
- Product
operationId: getAllProducts
description: 'Retrieve all products available for purchase, in a single list. Products can be filtered by category by using the `category` query parameter. If a category is not supplied or the category is invalid, all products will be returned.
'
summary: Princess Beef Heavy Industries Get a list of all products.
responses:
'200':
$ref: '#/components/responses/ProductList'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AuthorizationError'
'429':
$ref: '#/components/responses/ServerError'
'500':
$ref: '#/components/responses/ServerError'
/products/{id}:
get:
security:
- {}
tags:
- Product
operationId: getProductById
description: 'Get a specific product by its unique identifier (`id`) or by its short code (`shortCode`) values. If the product does not exist, a 404 error will be returned.
'
summary: Princess Beef Heavy Industries Get a product by its `id` or `shortCode`
parameters:
- $ref: '#/components/parameters/ProductPathId'
responses:
'200':
$ref: '#/components/responses/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/ServerError'
'500':
$ref: '#/components/responses/ServerError'
delete:
security:
- ApiKeyAuth:
- delete:products
tags:
- Product
operationId: deleteProduct
description: Remove a product from the database.
summary: Princess Beef Heavy Industries Remove a product
parameters:
- $ref: '#/components/parameters/ProductPathId'
responses:
'200':
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/ServerError'
'500':
$ref: '#/components/responses/ServerError'
post:
security:
- ApiKeyAuth:
- write:products
tags:
- Product
operationId: updateProductById
requestBody:
description: The updated product.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
examples:
updatedProduct:
$ref: '#/components/examples/NewProductExample'
description: 'Update a specific product by its unique identifier. If the product does not exist, a 404 error will be returned.
'
summary: Princess Beef Heavy Industries Update a product
parameters:
- $ref: '#/components/parameters/ProductPathId'
responses:
'200':
$ref: '#/components/responses/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/ServerError'
'500':
$ref: '#/components/responses/ServerError'
/search:
get:
security:
- {}
tags:
- Product
operationId: searchProducts
description: Search products for a keyword.
summary: Princess Beef Heavy Industries Search products.
parameters:
- $ref: '#/components/parameters/KeywordSearch'
responses:
'200':
$ref: '#/components/responses/ProductList'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/ServerError'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
ProductList:
type: array
description: A list of all products available for purchase.
minItems: 0
maxItems: 1000
items:
$ref: '#/components/schemas/Product'
example:
- id: d1404c5c-69bd-4cd2-a4cf-b47c79a30112
shortCode: pb0001
name: pb33f t-shirt
description: An example t-shirt with the pb33f logo on it.
price: 19.99
category: shirts
image: https://pb33f.io/images/t-shirt.png
- id: 50cf5a6e-9bc1-4abf-846c-e6b33a2ccd11
shortCode: pb0002
name: pb33f hoodie
description: An example hoodie with the pb33f logo on it.
price: 29.99
category: hoodies
image: https://pb33f.io/images/hoodie.png
Product:
description: A product is something that can be sold by the gift shop
type: object
required:
- id
- shortCode
- name
- description
- price
- category
- image
properties:
id:
type: string
maxLength: 50
format: uuid
description: The unique identifier for the product
example: d1404c5c-69bd-4cd2-a4cf-b47c79a30112
shortCode:
type: string
maxLength: 50
format: string
description: A short code for the product, easily human readable
example: pb0001
name:
type: string
description: The name of the product
maxLength: 50
format: string
example: pb33f t-shirt
description:
type: string
description: A description of the product
maxLength: 500
format: string
example: A t-shirt with the pb33f logo on the front
price:
type: number
format: float
description: The price of the product, as a floating point number
example: 19.99
category:
type: string
maxLength: 50
format: string
description: The category of the product
example: shirts
image:
type: string
maxLength: 100
format: string
description: The URL of the product image
example: https://pb33f.io/images/t-shirt.png
example:
id: d1404c5c-69bd-4cd2-a4cf-b47c79a30112
shortCode: pb0001
name: pb33f t-shirt
description: A t-shirt with the pb33f logo on the front
price: 19.99
category: shirts
image: https://pb33f.io/images/t-shirt.png
Error:
type: object
description: An error response from the API
example:
type: failure
title: Something went wrong
status: 500
detail: A problem happened when we were doing something
instance: https://pb33f.io/errors/general
properties:
type:
type: string
maxLength: 100
format: string
description: The URI of the error type.
example: https://quobix.com/vacuum/tube/error
title:
description: A short, human-readable summary of the problem type.
type: string
maxLength: 200
format: string
example: Bad Request
status:
description: The HTTP status code applicable to this problem, expressed as a string value.
type: integer
minimum: 100
maximum: 500
format: int32
example: 400
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
maxLength: 500
format: string
example: The URL supplied was not valid or could not be processed correctly.
instance:
description: 'A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
'
type: string
maxLength: 500
format: string
example: https://quobix.com/vacuum/tube/error/400
parameters:
Category:
name: category
in: query
description: Category to filter products by. Should be the name of a category, e.g. `shirts`.
schema:
type: string
maxLength: 50
format: string
example: shirts
ProductPathId:
name: id
in: path
required: true
description: Product ID of the item to retrieve.
schema:
type: string
maxLength: 36
format: uuid
example: 50cf5a6e-9bc1-4abf-846c-e6b33a2ccd11
KeywordSearch:
name: query
in: query
required: true
description: The search string to use when searching for products.
schema:
type: string
maxLength: 50
format: string
example: hacker
headers:
Retry-After:
description: The number of seconds to wait before retrying the request.
schema:
type: integer
minimum: 1
maximum: 10000
format: int32
example: 1000
X-RateLimit-Limit:
description: The number of requests allowed in the current period.
schema:
type: integer
minimum: 1
maximum: 10000
format: int32
example: 1000
responses:
ServerError:
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
description: Something went wrong and a server error occurred, unable to process the request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
serverError:
summary: Example of a server error.
value:
message: Something went wrong and a server error occurred, unable to process the request.
code: server-error
url: https://pb33f.io/errors/server-error
NotFound:
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
description: The item requested could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notFound:
summary: Not Found
value:
message: The item requested does not exist or could not be found.
code: not-found
url: https://pb33f.io/errors/not-found
AuthorizationError:
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
description: Unauthorized request, you must be authenticated to perform this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
serverError:
summary: Sorry, computer said no.
value:
message: This request requires authentication. You are not authenticated.
code: authentication
url: https://pb33f.io/errors/authentication
Product:
description: Product is a single product object.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
BadRequest:
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
description: A bad request, the URL supplied was not valid or could not be processed correctly.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
badRequest:
summary: Example of a bad request
value:
message: The URL supplied was not valid or could not be processed correctly.
code: bad-request
url: https://pb33f.io/errors/bad-request
ProductList:
description: ProductList is an array of Product objects.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
examples:
NewProductExample:
summary: A product to create
description: An example of a product that can be returned by the API.
value:
id: abc-def
shortCode: pb0001
name: pb33f t-shirt
description: A t-shirt with the pb33f logo on it.
price: 19.99
category: shirts
image: https://pb33f.io/images/t-shirt.png
securitySchemes:
ApiKeyAuth:
description: 'API Key authentication. Provide your API key as the value of the `X-API-Key` header.
'
type: apiKey
in: header
name: X-API-Key