# Pet Store API - Underconstruction!

{% hint style="danger" %}
**Disclaimer**\
\
This is a portfolio sample. <mark style="color:red;">Please keep in mind that</mark>**:**

* 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](https://editor.swagger.io/?_gl=1*19rcx4y*_gcl_au*MzYxNTk3MTI3LjE3NTYyMjUyNzg.).
* I've followed an API-design methodology using Claude and Gemini as project companions.
* I focused on some features of the Pet Store.
  {% endhint %}

## Overview

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

The Pet Store API implements ***r**eusable data structure*, *request bodies*, and *security scheme*s, and uses two types of authentication (*OAuth2* - for operations requiring user-specific permissions, and *API Keys -* for operations securit&#x79;*)*.

## 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 functionalitie**s** **to manage your pet store business** including pets, users, and orders management.

The Pet Store API implements ***r**eusable data structure*, *request bodies*, and *security scheme*s, and uses two types of authentication (*OAuth2* - for operations requiring user-specific permissions, and *API Keys -* for operations securit&#x79;*)*.

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

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

### Security Fundamentals

Regarding authentication and authorizatio&#x6E;**,** 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:

<table><thead><tr><th width="238">Security Method</th><th width="156">Scope</th><th>Description</th></tr></thead><tbody><tr><td><strong>OAuth2 (Implicit flow)</strong></td><td><code>write:pets</code><br><code>read:pets</code></td><td><p>OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service.</p><p>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).<br></p></td></tr><tr><td><strong>API Key</strong></td><td><em>N/A</em></td><td><p>API Key authentication is a simple way of securing access by including a key in the request header.</p><p><br>This method is typically used for server-to-server communication.</p></td></tr></tbody></table>

#### Security Method and Endpoints

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

<table><thead><tr><th width="179">Security Method</th><th width="390">Endpoint</th><th>Scope</th></tr></thead><tbody><tr><td><strong>OAuth2 ('petstore_auth')</strong></td><td><code>/pet</code><br><code>/pet/findByStatus</code><br><code>/pet/findByTags</code><br><code>/pet/{petId}</code><br><code>/pet/{petId}</code><br><code>/store/order</code></td><td><code>write:pets</code><br><code>read:pets</code></td></tr><tr><td><strong>API Key ('api_key')</strong></td><td><code>/store/inventory</code><br><code>/pet/{petId}</code></td><td></td></tr></tbody></table>

#### Implementing OAuth2 (Implicit Flow)

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

<table><thead><tr><th width="238">Topic</th><th>Information</th></tr></thead><tbody><tr><td><strong>Authorization URL</strong></td><td>https://petstore3.swagger.io/oauth/authorize></td></tr><tr><td><strong>Scopes</strong></td><td><code>write:pets</code>: Allows modification of pets in your account.<br><code>read:pets</code>: Allows reading your pets.</td></tr></tbody></table>

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** | <p><strong><code>name: 'api\_key'</code></strong><br><strong><code>location: 'header'</code></strong></p> |

**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` \\

### *<mark style="color:orange;">(Coming soon!) Endpoints and Methods</mark>*

#### `/endpoint`

*Method description*

*Sample Request*

*Sample/Response Definitions Schema*

### *<mark style="color:orange;">(Coming soon!)</mark>* *<mark style="color:orange;">Request Parameters</mark>*

### *<mark style="color:orange;">(Coming soon!) Response Schema</mark>*

### *<mark style="color:yellow;">(Section under review!)</mark>* <mark style="color:yellow;">Status and Error Codes Handling</mark>

#### `/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 | *<mark style="color:orange;">TO DO</mark>* |

***POST***

| Status Code | Description          | Solution                                   |
| ----------- | -------------------- | ------------------------------------------ |
| **'200'**   | Successful operation | *N/A*                                      |
| **'400'**   | Invalid input        | *Review your input structure*              |
| **'422'**   | Validation exception | *<mark style="color:orange;">TO DO</mark>* |

#### `/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 | *<mark style="color:orange;">TO DO</mark>* |

***POST***

| Status Code | Description          | Solution                                   |
| ----------- | -------------------- | ------------------------------------------ |
| **'200'**   | Successful operation | *N/A*                                      |
| **'400'**   | Invalid input        | *Review your input structure*              |
| **'422'**   | Validation exception | *<mark style="color:orange;">TO DO</mark>* |

#### `/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*                |