REST APIs power most of the modern web. If you've ever used a web application, you've interacted with a REST API. In this tutorial, you'll learn how to use REST API endpoints using the Pet Store API, and understand why REST remains the most popular API protocol today.
REST stands for Representational State Transfer. It's an architectural style that defines a set of rules for building web services. REST APIs use HTTP methods to perform operations on resources.
The key principles include:
These principles make REST APIs simple, scalable, and easy to understand.
REST has become the standard for web APIs for good reasons. First, it works with standard HTTP methods. You already know GET, POST, PUT, and DELETE from browsing the web. REST just applies these methods to data operations.
Second, REST is language-agnostic. Your client can be written in JavaScript, Python, or any language. The server responds with JSON, which every language can parse.
Third, REST is well-documented and widely understood. When you hire developers, they likely already know REST. Training new team members becomes easier.
Finally, REST handles standard CRUD operations beautifully. Create, Read, Update, and Delete map directly to HTTP methods.
Let's explore the Pet Store API's CRUD endpoints. You'll learn to manage pet data using proper REST conventions.
Start by fetching a list of pets. The GET method retrieves data without any side effects.
curl "https://api.petstoreapi.com/v1/pets?status=AVAILABLE&page=1&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
The server responds with a wrapped collection including pagination metadata:
{
"data": [
{
"id": "pet_fYrZzCW9E1WIOyGw",
"name": "Buddy",
"species": "DOG",
"status": "AVAILABLE",
"category": {
"id": "cat_123",
"name": "Dogs"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalItems": 145,
"totalPages": 8
},
"links": {
"self": "https://api.petstoreapi.com/v1/pets?page=1",
"next": "https://api.petstoreapi.com/v1/pets?page=2"
}
}
You can also fetch a single pet by ID:
curl "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw" \
-H "Authorization: Bearer YOUR_API_KEY"
This returns only the specific pet you requested. Notice how the URI clearly identifies the resource: /v1/pets/pet_fYrZzCW9E1WIOyGw points to a specific pet.
Now add a new pet to your store. The POST method creates new resources.
curl -X POST "https://api.petstoreapi.com/v1/pets" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Buddy",
"species": "DOG",
"status": "AVAILABLE",
"category": {
"id": "cat_123",
"name": "Dogs"
}
}'
The server creates the pet and returns the complete object with a new ID. The response includes a 201 Created status, indicating a new resource was successfully created.
Notice the pattern: you send data in the request body, and the server responds with the created resource. This two-way communication is what makes REST powerful.
Update an existing pet using the PUT method for full replacement or PATCH for partial updates.
curl -X PUT "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Max",
"species": "DOG",
"status": "ADOPTED",
"category": {
"id": "cat_123",
"name": "Dogs"
}
}'
The server replaces all fields with your new data. For partial updates, use PATCH:
curl -X PATCH "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "ADOPTED"
}'
Remove a pet using the DELETE method.
curl -X DELETE "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw" \
-H "Authorization: Bearer YOUR_API_KEY"
The server removes the resource and returns a 204 No Content response. The resource is gone permanently.
REST APIs use HTTP status codes to communicate results. Understanding these codes helps you build robust applications.
When building your API client, handle these codes appropriately. Show meaningful error messages to users based on the status code.
REST APIs often support filtering through query parameters. The Pet Store API lets you filter pets by status, species, and more:
curl "https://api.petstoreapi.com/v1/pets?species=DOG&status=AVAILABLE&page=1&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
This returns only dogs with AVAILABLE status. Query parameters make APIs flexible without requiring additional endpoints.
Common query parameter patterns include:
?status=AVAILABLE - Filter by status (AVAILABLE, PENDING, ADOPTED)?species=DOG - Filter by species?page=1&limit=20 - Pagination?sort=ageMonths&order=ASC - SortingThese patterns help clients build powerful queries without requiring server changes.
Real-world APIs require authentication. The Pet Store API supports Bearer token authentication for protected endpoints.
curl "https://api.petstoreapi.com/v1/pets" \
-H "Authorization: Bearer YOUR_API_KEY"
Never expose your API keys in client-side code. Use environment variables and server-side proxying to keep keys secure.
HTTPS encrypts all traffic between your client and server. Always use HTTPS in production. The Pet Store API enforces HTTPS for all requests.
The Pet Store API provides a complete REST interface that's perfect for learning. It covers all CRUD operations, supports various data types, and includes practical features like filtering and authentication.
The documentation at docs.petstoreapi.com explains every endpoint in detail. Each method includes example requests and responses. You can test everything directly from your terminal.
Starting with a well-designed API like Pet Store API teaches good habits. You'll learn the correct patterns that transfer to any REST API you use in the future.
Now you understand REST fundamentals. Practice by building a small application that interacts with the Pet Store API. Try creating a command-line interface for managing pets, or a simple web frontend that displays pet data.
The skills you learned here apply to any REST API. Whether you're integrating with Stripe, Twilio, or your company's internal services, the patterns remain the same.
Explore the Pet Store API documentation at docs.petstoreapi.com to discover all available endpoints. Each one follows the REST principles you learned today.
