Instruments API

A mock REST API built using Visual Studio Code, Postman, and json-server; it manages a catalog of musical instruments. This project demonstrates API design, CRUD operations, and hands-on use of Postman for endpoint testing and documentation.

---

Overview

The Instruments API uses a local JSON file (db.json) as a datastore and exposes a set of RESTful endpoints for creating, reading, updating, and deleting instrument records. All requests and responses use JSON.

Base URL: http://localhost:3000

---

Data Model

Each instrument record contains the following fields:

Field	Type	Description
id	string	Unique identifier for the instrument record
instrument	string	Instrument category (e.g., bass, guitar, piano)
brand	string	Manufacturer or brand name
model	string	Model name or designation
year	string	Year of manufacture
type	array of strings	One or more descriptors (e.g., ["acoustic", "upright"])

Example Record

{
"id": "3",
"instrument": "bass",
"brand": "Kay",
"model": "M1-B",
"year": "1963",
"type": ["acoustic", "upright", "3/4-size"]
}

---

Getting Started

Prerequisites

• Node.js (v14 or later)
• npm

Installation

1. Clone the repository:

git clone https://github.com/j-gillespie/json-api.git
cd json-api

2. Install dependencies:

npm install

3. Start the server:

npm start

Once installed, the API is available at http://localhost:3000.

---

Endpoints

GET /instruments

Retrieves all instrument records from the datastore.

Request

GET /instruments

Response

[
{
"id": "1",
"instrument": "bass",
"brand": "Fender",
"model": "Jazz Bass",
"year": "1985",
"type": ["electric", "guitar"]
},
{
"id": "2",
"instrument": "bass",
"brand": "MusicMan",
"model": "StingRay",
"year": "N/A",
"type": ["electric", "guitar"]
}
]

---

POST /instruments

Adds a new instrument record to the datastore. The id field is auto-generated by json-server.

Request

POST /instruments
Content-Type: application/json

{
"instrument": "guitar",
"brand": "Fender",
"model": "Telecaster",
"year": "1972",
"type": ["electric"]
}

Response 201 Created

{
"id": "5060",
"instrument": "guitar",
"brand": "Fender",
"model": "Telecaster",
"year": "1972",
"type": ["electric"]
}

---

PUT /instruments/:id

Replaces an existing instrument record in full. You must include all fields in the request body; omitted fields will be removed.

Request

PUT /instruments/5060
Content-Type: application/json

{
"id": "5060",
"instrument": "guitar",
"brand": "Gibson",
"model": "Les Paul Standard",
"year": "1992",
"type": ["electric"]
}

Response 200 OK

{
"id": "5060",
"instrument": "guitar",
"brand": "Gibson",
"model": "Les Paul Standard",
"year": "1992",
"type": ["electric"]
}

---

PATCH /instruments/:id

Updates one or more fields of an existing instrument record without replacing the entire record.

Request

PATCH /instruments/5060
Content-Type: application/json

{
"year": "1985"
}

Response 200 OK

{
"id": "5060",
"instrument": "guitar",
"brand": "Gibson",
"model": "Les Paul Standard",
"year": "1985",
"type": ["electric"]
}

---

DELETE /instruments/:id

Removes an instrument record from the datastore by ID.

Request

DELETE /instruments/5060

Response 200 OK

{}

---

Filtering and Sorting

Json-server supports query parameters for filtering and sorting results without additional configuration.

Filter by Field

Use any field name as a query parameter to filter results.

Request

GET /instruments?instrument=bass

Returns all records where instrument equals bass.

---

Sort Results

Use _sort and _order to sort results by any field.

Request

GET /instruments?_sort=instrument&_order=asc

Returns all records sorted alphabetically by the instrument field in ascending order.

Supported values for _order: asc, desc

---

Postman Collection

A Postman collection (Instruments_postman_collection.json) is included in this repository. It contains pre-configured requests for all endpoints, including collection variables for base_url, instrument_id, field, and field_value.

Collection Variables

Variable	Default Value	Description
base_url	http://localhost:3000	API base URL
instrument_id	1	Target record ID for PUT, PATCH, DELETE
field	instrument	Field name for custom query filtering
field_value	bass	Field value for custom query filtering

Import Instructions

1. Open Postman.
2. Click Menu in the top-left corner, and select File > Import.
3. Upload Instruments.postman_collection.json.
4. Select the Instruments collection and begin sending requests.

---

Project Structure

json-api/
├── db.json # JSON datastore
├── package.json # Project configuration and start script
├── .gitignore # Excludes node_modules
├── Instruments.postman_collection.json # Postman requests for all endpoints
└── README.md # Project documentation

---

License

This project is intended as a portfolio sample demonstrating REST API structure, CRUD operations, and API documentation practices.