Petshop API (example)

Base URL:

Authentication: Bearer token required for all endpoints.

Overview

Welcome to the Petshop API documentation! This RESTful API allows you to manage pets, owners, appointments, and services for your pet store or veterinary clinic.

Rate Limit: 1000 requests per hour per API key.

Pets Management

Create Pet POST

Add a new pet to the system.

Endpoint: /pets

const newPet = await fetch('/pets', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
        name: 'Buddy',
        species: 'dog',
        breed: 'Golden Retriever',
        age: 3,
        owner_id: 12345,
        color: 'Golden',
        weight: 30.5
    })
});

const pet = await newPet.json();
console.log('Created pet:', pet);

import requests

response = requests.post('/pets', 
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'Buddy',
        'species': 'dog',
        'breed': 'Golden Retriever',
        'age': 3,
        'owner_id': 12345,
        'color': 'Golden',
        'weight': 30.5
    }
)

pet = response.json()
print(f'Created pet: {pet}')

curl -X POST '/pets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Buddy",
    "species": "dog",
    "breed": "Golden Retriever",
    "age": 3,
    "owner_id": 12345,
    "color": "Golden",
    "weight": 30.5
  }'

Success Response: Pet created with status code 201

Get Pet GET

Retrieve a specific pet’s information.

Endpoint: /pets/{pet_id}

const response = await fetch('/pets/123', {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const pet = await response.json();
console.log('Pet details:', pet);

import requests

response = requests.get('/pets/123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

pet = response.json()
print(f'Pet details: {pet}')

Update Pet PUT

Update an existing pet’s information.

Endpoint: /pets/{pet_id}

const updatedPet = await fetch('/pets/123', {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
        name: 'Buddy Updated',
        weight: 32.0,
        age: 4
    })
});

const pet = await updatedPet.json();
console.log('Updated pet:', pet);

import requests

response = requests.put('/pets/123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'Buddy Updated',
        'weight': 32.0,
        'age': 4
    }
)

pet = response.json()
print(f'Updated pet: {pet}')

Delete Pet DELETE

Remove a pet from the system.

Endpoint: /pets/{pet_id}

Warning: This action cannot be undone. All associated records will be removed.

const response = await fetch('/pets/123', {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

if (response.ok) {
    console.log('Pet deleted successfully');
}

import requests

response = requests.delete('/pets/123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

if response.status_code == 204:
    print('Pet deleted successfully')

Owners Management

Create Owner POST

Endpoint: /owners

const newOwner = await fetch('/owners', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
        first_name: 'Sarah',
        last_name: 'Johnson',
        email: 'sarah.johnson@email.com',
        phone: '+1-555-123-4567',
        address: {
            street: '123 Main St',
            city: 'Anytown',
            state: 'CA',
            zip_code: '12345'
        }
    })
});

const owner = await newOwner.json();
console.log('Created owner:', owner);

import requests

response = requests.post('/owners',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'first_name': 'Sarah',
        'last_name': 'Johnson',
        'email': 'sarah.johnson@email.com',
        'phone': '+1-555-123-4567',
        'address': {
            'street': '123 Main St',
            'city': 'Anytown',
            'state': 'CA',
            'zip_code': '12345'
        }
    }
)

owner = response.json()
print(f'Created owner: {owner}')

List Owners GET

Get all pet owners with pagination.

Endpoint: /owners

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 20, max: 100)
search (optional): Search by name or email

const response = await fetch('/owners?page=1&limit=10&search=sarah', {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();
console.log('Owners:', data.owners);
console.log('Total:', data.total);

import requests

params = {
    'page': 1,
    'limit': 10,
    'search': 'sarah'
}

response = requests.get('/owners',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params=params
)

data = response.json()
print(f'Owners: {data["owners"]}')
print(f'Total: {data["total"]}')

Appointments

Schedule Appointment POST

Book a new appointment for a pet.

Endpoint: /appointments

Business Hours: Monday-Friday 8:00 AM - 6:00 PM, Saturday 9:00 AM - 4:00 PM

const appointment = await fetch('/appointments', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
        pet_id: 123,
        service_type: 'checkup',
        appointment_date: '2024-02-15',
        appointment_time: '14:30',
        notes: 'Annual wellness check',
        veterinarian_id: 456
    })
});

const result = await appointment.json();
console.log('Scheduled appointment:', result);

import requests
from datetime import datetime

response = requests.post('/appointments',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'pet_id': 123,
        'service_type': 'checkup',
        'appointment_date': '2024-02-15',
        'appointment_time': '14:30',
        'notes': 'Annual wellness check',
        'veterinarian_id': 456
    }
)

appointment = response.json()
print(f'Scheduled appointment: {appointment}')

Success Response: Appointment scheduled with confirmation number

Get Available Slots GET

Check available appointment slots for a specific date.

Endpoint: /appointments/available

Query Parameters:

date (required): Date in YYYY-MM-DD format
service_type (optional): Filter by service type
veterinarian_id (optional): Filter by veterinarian

const response = await fetch('/appointments/available?date=2024-02-15&service_type=checkup', {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const slots = await response.json();
console.log('Available slots:', slots);

import requests

params = {
    'date': '2024-02-15',
    'service_type': 'checkup'
}

response = requests.get('/appointments/available',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params=params
)

slots = response.json()
print(f'Available slots: {slots}')

Services

List Services GET

Get all available pet services and their pricing.

Endpoint: /services

const response = await fetch('/services', {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const services = await response.json();
console.log('Available services:', services);

import requests

response = requests.get('/services',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

services = response.json()
print(f'Available services: {services}')

Medical Records

Add Medical Record POST

Add a new medical record for a pet.

Endpoint: /pets/{pet_id}/medical-records

HIPAA Compliance: All medical records are encrypted and access is logged.

const record = await fetch('/pets/123/medical-records', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
        visit_date: '2024-02-15',
        veterinarian_id: 456,
        diagnosis: 'Healthy - routine checkup',
        treatment: 'Vaccinations updated',
        medications: [
            {
                name: 'Rabies Vaccine',
                dosage: '1ml',
                frequency: 'Annual'
            }
        ],
        next_visit: '2025-02-15',
        notes: 'Pet is in excellent health'
    })
});

const medicalRecord = await record.json();
console.log('Medical record created:', medicalRecord);

import requests

response = requests.post('/pets/123/medical-records',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'visit_date': '2024-02-15',
        'veterinarian_id': 456,
        'diagnosis': 'Healthy - routine checkup',
        'treatment': 'Vaccinations updated',
        'medications': [
            {
                'name': 'Rabies Vaccine',
                'dosage': '1ml',
                'frequency': 'Annual'
            }
        ],
        'next_visit': '2025-02-15',
        'notes': 'Pet is in excellent health'
    }
)

medical_record = response.json()
print(f'Medical record created: {medical_record}')

Error Handling

Error Response Format: All errors follow a consistent JSON structure

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input data",
        "details": [
            {
                "field": "email",
                "message": "Email format is invalid"
            }
        ]
    }
}

Common HTTP Status Codes

Status	Description
`200`	Success
`201`	Created successfully
`400`	Bad Request - Invalid input
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Rate Limits

Current Limits:

Free Tier: 100 requests/hour
Pro Tier: 1,000 requests/hour
Enterprise: Unlimited

Rate limit headers are included in all responses.

SDKs and Tools

Official SDKs Available:

JavaScript/TypeScript
Python
PHP
Ruby
Go

Postman Collection: Available for easy API testing