Pet Store API - Underconstruction!

Disclaimer This is a portfolio sample. Please keep in mind that:

• The sole purpose of this page is to showcase my understanding and practice of API documentation.

• This content is made from the openapi specification of the Swagger Pet Store.

• I've followed an API-design methodology using Claude and Gemini as project companions.

• I focused on some features of the Pet Store.

Overview

The Pet Store API is a REST API that provides a comprehensive set of endpoints and functionalities to manage your pet store business including pets, users, and orders management.

The Pet Store API implements reusable data structure, request bodies, and security schemes, and uses two types of authentication (OAuth2 - for operations requiring user-specific permissions, and API Keys - for operations security).

Quick Start Guide

Adding Your First Pet to the Store

Searching for a Pet in the Store

Tutorials

Security

Authentication and Authorization

Authentication and Authorization

Best Practices

Parameters Options

API Calls and Thresholds

Reference Documentation

Overview

The Pet Store API is a REST API that provides a comprehensive set of endpoints and functionalities to manage your pet store business including pets, users, and orders management.

The Pet Store API implements reusable data structure, request bodies, and security schemes, and uses two types of authentication (OAuth2 - for operations requiring user-specific permissions, and API Keys - for operations security).

To work with the Pet Store API, we have designed the following endpoints:

Endpoint	Scope	Features
/pet	Get all pets stored in your shop.	By default, updates occur every 2 minutes.
/pet/findByStatus	Get pets by status (active, sold, reserved, incoming, ).	Allows combined statuses, for example: reserved and incoming.
pet/{petId}	Get pet by ID.	petId format is customizable.
/store/inventory	Get all pets in the store's inventory.	By default, Inventory is sorted by status.
/store/order/	Get all orders of the store.	By default, last orders are shown first.
/store/order/{orderId}	Get order by ID.	orderId format is customizable.
/user	Get all users of the store.	By default, users are updated every day (24 hours).
/user/login	Get all users currently logged in into the system.	By default, passwords are not shown. Access time is shown in the time zone of the current system.
/user/logout	Get all logged-out users.	Access time is shown in the time zone of the current system.
/user/{username}	Ger user information by username.	Case sensitive

Security Fundamentals

Regarding authentication and authorization, the Pet Store API uses the following types of authentication:

• OAuth2 - for operations requiring user-specific permissions

• API Keys - for operations security

Check the following table for more information:

Security Method	Scope	Description
OAuth2 (Implicit flow)	write:pets read:pets	OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. The Pet Store API uses the implicit flow of OAuth2, which is suitable for public clients that cannot keep a secret (such as single-page applications).
API Key	N/A	API Key authentication is a simple way of securing access by including a key in the request header. This method is typically used for server-to-server communication.

Security Method and Endpoints

Each security method is applied to specific endpoints as shown in the following table:

Security Method	Endpoint	Scope
OAuth2 ('petstore_auth')	/pet /pet/findByStatus /pet/findByTags /pet/{petId} /pet/{petId} /store/order	write:pets read:pets
API Key ('api_key')	/store/inventory /pet/{petId}

Implementing OAuth2 (Implicit Flow)

To implement OAuth2 authorization flow consider the information disclosed in the following table:

Topic	Information
Authorization URL	https://petstore3.swagger.io/oauth/authorize>
Scopes	write:pets: Allows modification of pets in your account. read:pets: Allows reading your pets.

The OAuth2 needs a request authorization, receive the access token, and uses the access token as described in the following steps:

1. Request authorization: Redirect the user to the authorization URL with the required parameters (client ID, redirect URI, response type, and scope), for example: https://petstore3.swagger.io/oauth/authorize?client_id=<YOUR_CLIENT_ID>&redirect_uri==<YOUR_REDIRECT_URI>&response_type=token&scope=write:pets read:pets

2. Receive access token:

   1. After the user grants permission, they are redirected back to your application with the access token in the URL fragment.

   2. Extract the access token from the URL.

3. Use access token: Include the access token in the ‘Authorization’ header for API requests, for example: GET /pet HTTP/1.1

   Host: petstore3.swagger.io

   Authorization: Bearer ACCESS_TOKEN

Implementing API Key

To implement the API Key authorization flow consider the information disclosed in the following table:

Topic	Information
API Key parameters	name: 'api_key' location: 'header'

To implement the API Key follow these steps:

1. Get the API Key: Get the API key from the API provider (usually through the API management portal).

2. Include the API key in your request: Add the API key to the request header, for example: GET /pet/{petId} HTTP/1.1 Host: petstore3.swagger.io api_key: YOUR_API_KEY \

(Coming soon!) Endpoints and Methods

/endpoint

Method description

Sample Request

Sample/Response Definitions Schema

(Coming soon!) Request Parameters

(Coming soon!) Response Schema

(Section under review!) Status and Error Codes Handling

/pet

PUT

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid ID supplied	Provide a valid ID
'404'	Pet not found	N/A
'422'	Validation exception	TO DO

POST

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid input	Review your input structure
'422'	Validation exception	TO DO

/pet/findByStatus

GET

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid status value	Provide a valid status value

/pet/{petId}

GET

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid ID supplied	Provide a valid ID
'404'	Pet not found	N/A

POST

Status Code	Description	Solution
'400'	Invalid ID supplied	Provide a valid ID

DELETE

Status Code	Description	Solution
'400'	Invalid pet value	Provide a valid ID

/store/order/{orderId}

GET

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid ID supplied	Provide a valid ID
'404'	Order not found	N/A

DELETE

Status Code	Description	Solution
'400'	Invalid ID supplied	Provide a valid ID
'404'	Order nor found	N/A

/pet

PUT

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid ID supplied	Provide a valid ID
'404'	Pet not found	N/A
'422'	Validation exception	TO DO

POST

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid input	Review your input structure
'422'	Validation exception	TO DO

/pet/findByStatus

GET

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid status value	Provide a valid status value

/pet/{petId}

GET

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid ID supplied	Provide a valid ID
'404'	Pet not found	N/A

POST

Status Code	Description	Solution
'400'	Invalid ID supplied	Provide a valid ID

DELETE

Status Code	Description	Solution
'400'	Invalid pet value	Provide a valid ID

/store/order/{orderId}

GET

Status Code	Description	Solution
'200'	Successful operation	N/A
'400'	Invalid ID supplied	Provide a valid ID
'404'	Order not found	N/A

DELETE

Status Code	Description	Solution
'400'	Invalid ID supplied	Provide a valid ID
'404'	Order not found	N/A