API Reference
Welcome to the Store Endpoints reference for our Flask-RESTful demo API. This section covers all routes related to store management: creating, retrieving, deleting, and listing stores. Internally, stores are represented by the StoreModel class (in models/store.py) and exposed via the Store and StoreList resources (in resources/store.py) .
Index
Overview
The Store endpoints allow clients to:
- Create a new store by name
- Retrieve a store’s details, including its associated books
- Delete a store
- List all stores in the system
Each endpoint is registered in app.py as follows:
api.add_resource(Store, '/store/<string:name>')
api.add_resource(StoreList, '/stores')
Under the hood, StoreModel is a SQLAlchemy model with:
- id (Integer, PK)
- name (String)
- books (One-to-many relationship to
BookModel, lazy loaded)
Key methods on StoreModel include:
find_by_name(name)– lookup by namejson()– serialize to{'name': ..., 'books': [...]}save_to_db()/delete_from_db()– persistence operations
Endpoint Summary
| Endpoint | Method | Description |
|---|---|---|
| /store/{name} | GET | Retrieve a single store by name |
| /store/{name} | POST | Create a new store |
| /store/{name} | DELETE | Delete an existing store |
| /stores | GET | List all stores |
GET /store/{name}
Retrieve a store by its unique name, returning its details and associated books.
{
"title": "Retrieve Store",
"description": "Fetches a single store and its books by store name.",
"method": "GET",
"baseUrl": "http://localhost:5000",
"endpoint": "/store/{name}",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "name",
"value": "The name of the store to retrieve.",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"responses": {
"200": {
"description": "Store found",
"body": "{\"name\": \"MyBookstore\", \"books\": []}"
},
"404": {
"description": "Store not found",
"body": "{\"message\": \"Store not found\"}"
}
}
}
Behavior
- On success, returns HTTP 200 with the store’s JSON payload.
- If no store exists with the given name, returns HTTP 404.
POST /store/{name}
Create a new store identified by name. Names must be unique.
{
"title": "Create Store",
"description": "Creates a new store with the specified name.",
"method": "POST",
"baseUrl": "http://localhost:5000",
"endpoint": "/store/{name}",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": false
}
],
"queryParams": [],
"pathParams": [
{
"key": "name",
"value": "The unique name for the new store.",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"responses": {
"201": {
"description": "Store created successfully",
"body": "{\"name\": \"NewStore\", \"books\": []}"
},
"400": {
"description": "Store already exists",
"body": "{\"message\": \"A store with name 'NewStore' already exists.\"}"
},
"500": {
"description": "Server error on creation",
"body": "{\"message\": \"An error occurred creating the store.\"}"
}
}
}
Behavior
- Returns HTTP 201 with the new store’s JSON when creation succeeds.
- Returns HTTP 400 if a store with that name already exists.
- Returns HTTP 500 if a database error occurs during save.
DELETE /store/{name}
Delete an existing store by its name.
{
"title": "Delete Store",
"description": "Removes the store with the given name.",
"method": "DELETE",
"baseUrl": "http://localhost:5000",
"endpoint": "/store/{name}",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "name",
"value": "The name of the store to delete.",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"responses": {
"200": {
"description": "Store deleted (if it existed)",
"body": "{\"message\": \"Store deleted\"}"
}
}
}
Behavior
- Always returns HTTP 200 with a deletion confirmation message.
- If the store did not exist, the same confirmation message is returned.
GET /stores
List all stores currently in the database.
{
"title": "List All Stores",
"description": "Retrieves a list of all stores, each with its books.",
"method": "GET",
"baseUrl": "http://localhost:5000",
"endpoint": "/stores",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"responses": {
"200": {
"description": "A list of stores",
"body": "{\"stores\": [{\"name\": \"Store1\", \"books\": []}, {\"name\": \"Store2\", \"books\": []}]}"
}
}
}
Behavior
- Returns HTTP 200 with an array of all stores and their book listings.
Implementation Details
-
Resource Classes
Storehandles GET, POST, DELETE for/store/<name>.StoreListhandles GET for/stores.
Both extendflask_restful.Resourceand interact with theStoreModel.
-
Model Layer
StoreModel(inmodels/store.py) defines the database schema and provides helper methods likefind_by_name,save_to_db, anddelete_from_db.
-
Error Handling
- Standard HTTP codes are used:
- 200: Success (retrieval, deletion).
- 201: Resource created.
- 400: Bad request (duplicate name).
- 404: Not found.
- 500: Server/database errors.
- Standard HTTP codes are used:
This completes the Store Endpoints documentation. For more information on authentication, book resources, or user registration, refer to their respective sections.