# Pet Store

## Overview

Petstore API is a simple, sample API for managing pets.

## API information

| Item | Value |
|---|---|
| API name | Petstore API |
| Version | `1.0.0` |
| Description | A sample API for pets |

## Base URL

All requests are made relative to:

- `https://api.petstore.com/v1`

## Authentication (API key)

This API uses an API key passed via the `X-API-Key` request header.

- Learn more in [Authentication](authentication.html)

## Versioning

The API is versioned in the URL path:

- Current: `v1` (e.g., `https://api.petstore.com/v1/...`)

If a new major version is introduced, expect it to appear as a new base path (for example, `/v2`).

## Quickstart

### 1) Set your API key

Export an environment variable to avoid pasting keys into command history:

```bash
export PETSTORE_API_KEY="YOUR_API_KEY"
```

### 2) Make a request (curl)

Example: list pets (see full details in [Pets](endpoints/pets.html)):

```bash
curl -sS \
  -H "X-API-Key: ${PETSTORE_API_KEY}" \
  "https://api.petstore.com/v1/pets"
```

### 3) Make a request (JavaScript / Node.js)

```js
const url = "https://api.petstore.com/v1/pets";

async function main() {
  const res = await fetch(url, {
    headers: {
      "X-API-Key": process.env.PETSTORE_API_KEY,
    },
  });

  if (!res.ok) {
    throw new Error(`Request failed: ${res.status} ${res.statusText}`);
  }

  const data = await res.json();
  console.log(data);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

## Next steps

- Review auth requirements: [Authentication](authentication.html)
- Explore endpoints:
  - [Pets](endpoints/pets.html) (Pet operations)
  - [Store](endpoints/store.html) (Store operations)
  - [Miscellaneous](endpoints/untagged.html) (Untagged/operational endpoints)
- Understand data models: [Schemas](schemas.html)
- Troubleshoot failures: [Errors](errors.html)

---

## Authentication

This API uses an API key passed via the `X-API-Key` request header.

## API key authentication (`X-API-Key`)

### How it works

Include your API key in every request using the `X-API-Key` header.

| Item | Value |
|---|---|
| Security scheme | `apiKey` |
| Header name | `X-API-Key` |
| Location | HTTP header |

### Example requests

#### curl

```bash
curl -X GET "<BASE_URL>/pets" \
  -H "X-API-Key: YOUR_API_KEY"
```

#### JavaScript (fetch)

```js
const baseUrl = process.env.PETSTORE_BASE_URL;
const apiKey = process.env.PETSTORE_API_KEY;

const res = await fetch(`${baseUrl}/pets`, {
  method: "GET",
  headers: {
    "X-API-Key": apiKey,
  },
});

if (!res.ok) {
  throw new Error(`Request failed: ${res.status} ${res.statusText}`);
}

const data = await res.json();
console.log(data);
```

## Security notes & best practices

- **Treat API keys like passwords**: do not embed keys in client-side code or commit them to source control.
- **Use environment variables or a secrets manager** to store and inject the API key at runtime.
- **Rotate keys regularly** and immediately rotate/revoke any key that may be exposed.
- **Use TLS (HTTPS) only**: API keys must not be sent over unencrypted connections.
- **Least privilege**: if multiple keys/scopes exist in your environment, use the smallest access needed per app or service.

## Troubleshooting

- If you receive `401 Unauthorized` or `403 Forbidden`, verify:
  - The `X-API-Key` header is present and spelled exactly as shown.
  - The key value is correct and not expired/revoked.
  - You are calling the correct environment/base URL.

For common error formats and guidance, see [Errors](errors.html).

## Related documentation

- [Overview](index.html) (base URLs, quickstart)
- [Pets endpoints](endpoints/pets.html)
- [Store endpoints](endpoints/store.html)
- [Miscellaneous endpoints](endpoints/untagged.html)
- [Schemas](schemas.html)
- [Errors](errors.html)

---

## Pets

Endpoints for listing, creating, and retrieving pets.

**Authentication:** These endpoints use an API key provided via the `X-API-Key` header. See [Authentication](../authentication.html).

**Related schemas:** [`Pet`](../schemas.html#pet), [`CreatePetRequest`](../schemas.html#createpetrequest) (see [Schemas](../schemas.html)).

---

## List all pets

`GET /pets`

Returns a list of pets. Optionally limit the number of results.

### Query parameters

| Name | In | Type | Required | Description |
|---|---|---:|:---:|---|
| `limit` | query | integer | No | Maximum number of pets to return. |

### Request example

```bash
curl -sS \
  -H "X-API-Key: $API_KEY" \
  "https://api.example.com/pets?limit=10"
```

### Responses

#### 200 OK

A JSON array of [`Pet`](../schemas.html#pet).

**Response example**

```json
[
  {
    "id": "pet_123",
    "name": "Mochi",
    "tag": "cat"
  },
  {
    "id": "pet_456",
    "name": "Rex",
    "tag": "dog"
  }
]
```

#### 500 Server error

The server encountered an unexpected condition.

---

## Create a pet

`POST /pets`

Creates a new pet.

### Request body

Content type: `application/json`

Schema: [`CreatePetRequest`](../schemas.html#createpetrequest)

| Field | Type | Required | Description |
|---|---|:---:|---|
| `name` | string | Yes | Pet name. |
| `tag` | string | No | Optional category/tag (e.g., `dog`, `cat`). |

### Request example

```bash
curl -sS -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mochi","tag":"cat"}' \
  "https://api.example.com/pets"
```

### Responses

#### 201 Created

Returns the created [`Pet`](../schemas.html#pet).

**Response example**

```json
{
  "id": "pet_789",
  "name": "Mochi",
  "tag": "cat"
}
```

#### 400 Bad request

The request body was invalid (for example, missing required fields like `name`). See [Errors](../errors.html) for troubleshooting guidance.

---

## Get a pet by ID

`GET /pets/{petId}`

Retrieves a single pet by its unique identifier.

### Path parameters

| Name | In | Type | Required | Description |
|---|---|---|:---:|---|
| `petId` | path | string | Yes | The pet ID to retrieve. |

### Request example

```bash
curl -sS \
  -H "X-API-Key: $API_KEY" \
  "https://api.example.com/pets/pet_123"
```

### Responses

#### 200 OK

Returns a [`Pet`](../schemas.html#pet).

**Response example**

```json
{
  "id": "pet_123",
  "name": "Mochi",
  "tag": "cat"
}
```

#### 404 Pet not found

No pet exists for the provided `petId`. See [Errors](../errors.html) for recommended handling.

---

## Store

This section covers store-related endpoints, such as inventory retrieval.

## Base URL

All endpoints in this section are served from:

- `https://api.petstore.com/v1`

## Authentication

This API uses an API key sent via the `X-API-Key` header.

**Header example**

```http
X-API-Key: YOUR_API_KEY
```

For full details, see [Authentication](../authentication.html).

---

## Get inventory

`GET /store/inventory`

Get current inventory counts.

### Request

**Headers**

| Name | In | Type | Required | Description |
|---|---|---:|:---:|---|
| `X-API-Key` | header | string | Yes | API key used to authenticate requests. |

**Query parameters**

None.

**Request body**

None.

### Responses

| Status | Description |
|---:|---|
| 200 | Inventory counts |

#### 200 OK (example)

The response returns inventory counts (example payload):

```json
{
  "available": 12,
  "pending": 3,
  "sold": 7
}
```

> Note: The OpenAPI response description is **"Inventory counts"**. If you need the exact response schema/fields, check the API spec or contact the API provider.

### Code examples

**curl**

```bash
curl -X GET "https://api.petstore.com/v1/store/inventory" \
  -H "X-API-Key: YOUR_API_KEY"
```

---

## Related

- Other endpoints: [Pets](pets.html), [Miscellaneous](untagged.html)
- Error handling: [Errors](../errors.html)
- Data models: [Schemas](../schemas.html)

---

## Schemas

This section documents the core data models used by the API.

Related endpoints:
- [Pets endpoints](endpoints/pets.html)

## Pet
Represents a pet resource as returned by the API.

### Fields
| Field | Type | Required | Description |
|---|---|---:|---|
| `id` | `string` | Yes | Unique identifier for the pet. |
| `name` | `string` | Yes | Display name of the pet. |
| `tag` | `string` | No | Optional tag/category for the pet (e.g., `dog`, `cat`). |

### Example
```json
{
  "id": "pet_123",
  "name": "Fido",
  "tag": "dog"
}
```

## CreatePetRequest
Request body used to create a new pet.

### Fields
| Field | Type | Required | Description |
|---|---|---:|---|
| `name` | `string` | Yes | Name of the pet to create. |
| `tag` | `string` | No | Optional tag/category for the pet. |

### Example
```json
{
  "name": "Whiskers",
  "tag": "cat"
}
```

## Notes
- `tag` is optional on both models; omit it if you don’t need categorization.
- The `id` field is required on `Pet` objects returned by the API, but is not provided in `CreatePetRequest`.

---

## Errors

This API uses standard HTTP status codes to indicate success or failure. When a request fails, inspect the HTTP status code first, then review the response body (if present) and any correlation/request IDs returned by your gateway or reverse proxy.

Related sections:

- Authentication: [authentication.html](authentication.html)
- Pets endpoints: [endpoints/pets.html](endpoints/pets.html)
- Schemas: [schemas.html](schemas.html)

## Common error responses

The following errors are commonly returned by the API (including documented **400**, **404**, and **500** cases).

> Tip: In addition to these, you may also see authentication/authorization failures (often 401/403). See [authentication.html](authentication.html) for details.

| Status | Meaning | Common causes | What to do |
|---:|---|---|---|
| 400 | Bad Request | Invalid JSON, missing required fields, invalid query parameter values, invalid enum value | Validate payload and query parameters; check required fields and types; ensure `Content-Type: application/json` when sending JSON. |
| 404 | Not Found | Resource ID does not exist; wrong path; using an ID from a different environment | Confirm the URL and HTTP method; verify the ID exists; re-check base URL and path parameters. |
| 500 | Internal Server Error | Unhandled server error, downstream dependency failure, unexpected edge cases | Retry with backoff for transient failures; capture request/response details and contact support with timestamps and any request IDs. |

## 400 Bad Request

### When it happens

A **400** typically indicates the server received the request but could not process it due to a client-side issue.

Common examples:

- Malformed JSON (e.g., missing a closing brace)
- Missing required fields in the request body
- Invalid query parameter values (wrong type/format)
- Unsupported values for constrained fields (enums)

### Troubleshooting checklist

1. Ensure the request body is valid JSON.
2. Ensure you are sending the right `Content-Type` header:

   - `Content-Type: application/json`

3. Verify required fields and types (see [schemas.html](schemas.html)).
4. Re-check endpoint-specific requirements (see [endpoints/pets.html](endpoints/pets.html)).

### Example

**Request (invalid JSON)**

```bash
curl -X POST "https://api.example.com/pets" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name": "Mochi", "tag": "cat"'
```

**Response (example)**

```json
{
  "error": {
    "code": "bad_request",
    "message": "Malformed JSON payload"
  }
}
```

## 404 Not Found

### When it happens

A **404** indicates the requested resource does not exist (or the path is incorrect).

Common examples:

- Requesting a pet by an ID that is not present
- Using an incorrect URL (missing a path segment)
- Calling the right URL with the wrong HTTP method

### Troubleshooting checklist

1. Confirm you’re calling the correct endpoint and method (see [endpoints/pets.html](endpoints/pets.html)).
2. Verify the ID exists by listing resources first (if supported) and then retrieving by ID.
3. Confirm the environment/base URL (dev vs prod).

### Example

**Request**

```bash
curl -X GET "https://api.example.com/pets/999999" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Response (example)**

```json
{
  "error": {
    "code": "not_found",
    "message": "Pet not found"
  }
}
```

## 500 Internal Server Error

### When it happens

A **500** indicates an unexpected condition prevented the server from fulfilling the request.

This can be caused by:

- A transient failure in a downstream dependency (database, cache, third-party integration)
- An unhandled server-side exception
- Rare input edge cases

### Troubleshooting checklist

1. Retry the request with exponential backoff (especially for idempotent operations like GET).
2. If the error persists, capture:

   - Timestamp (with timezone)
   - Endpoint path + method
   - Request headers (excluding sensitive values)
   - Request body (redact sensitive data)
   - Full response body

3. Contact support and include any correlation/request IDs if returned by your infrastructure.

### Example

**Response (example)**

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}
```

## Handling and retry guidance

### Retries

- **Safe to retry** (generally): `GET` and other idempotent operations.
- **Retry with caution**: `POST`/non-idempotent operations (may create duplicates). If the API supports idempotency keys, use them.

Suggested retry strategy for transient failures:

- Initial delay: 250–500 ms
- Backoff: exponential (e.g., 2x)
- Jitter: add random 0–100 ms
- Max attempts: 3–5

### Logging recommendations

Log enough to reproduce and debug without storing secrets:

- HTTP method + path
- Status code
- Latency
- Request ID / correlation ID (if present)
- Sanitized request/response bodies

## Frequently seen causes

| Symptom | Likely status | Likely cause | Fix |
|---|---:|---|---|
| JSON parse error | 400 | Invalid JSON | Validate JSON; ensure correct quoting/escaping. |
| Missing required field | 400 | Request schema violation | Check [schemas.html](schemas.html) for required properties. |
| "Pet not found" | 404 | Incorrect/nonexistent ID | List pets first, then fetch by a valid ID. |
| Intermittent failures | 500 | Transient dependency issues | Retry with backoff; escalate if persistent. |

---