API Server
Author: Billy Bunn
Extensible REST API server with CRUD methods. Intended to integrate various data models through a common API. Built with Express in Node.js.
Currently, the app has examples of a CRUD interface for:
- JavaScript memory (for initial development)
- MongoDB (with Mongoose schemas)
- PostgreSQL
- Neo4j
Links and Resources
- JSdoc API Documentation
- Swagger Documentation
- Travis CI (continuous integration)
Endpoints
CRUD Routes
See links for examples of each method.
Route | API V1 Middleware | HTTP Method | CRUD Operation | Status Code |
---|---|---|---|---|
/api/v1/:model , /api/v1/:model/:id |
handleGetAll, handleGetOne | GET |
Read | 200 (OK), 404 (Not Found) |
/api/v1/:model/:id |
handlePost | POST |
Create | 200 (OK), 404 (Not Found) |
/api/v1/:model/:id |
handlePut | PUT |
Update | 200 (OK), 204 (No Content), 404 (Not Found) |
/api/v1/:model/:id |
handleDelete | DELETE |
Delete | 200 (OK), 404 (Not Found) |
Additional Routes
Route | Result |
---|---|
/api/v1/models |
API V1: Sends an array of all available data models. |
/api/v1/:model/schema |
API V1: Sends the schema of the model in JSON format |
/docs |
Serves static JSDoc generated site |
Installation
Get a local version of this server running with the following steps:
-
Clone the repository to your machine
-
Navigate to the repository and install all dependencies (listed in the
package.json
)cd api-server basic npm i
-
Create a file named
.env
in the repository's root directory and add the following variables:PORT
- defaults to3000
MONGODB_URI
- a standard connection string to a running MongoDB instance. Read more about setting up MongoDB on your machine here.
Example:
MONGODB_URI=mongodb://localhost:27017/api-server PORT=3000
-
Run the server and visit
localhost:3000
in your browser to see it running.node path/to/api-server-basic
Consider using nodemon to make development easier.
CRUD Operation Examples
POST
Add records to the database
Example
The app comes with some example data models using both JavaScript memory and MongoDB.Here are a few entries using HTTPie you can paste directly to you terminal to get started. You'll need HTTPie installed and your server up and running with a good mongoose connection.
Add a couple teams to MongoDB
echo '{
"name":"River Cats"
}' | http :3000/api/v1/teams
echo '{
"name":"Mariners"
}' | http :3000/api/v1/teams
Add some players to each team
echo '{
"name":"Billy",
"position":"1B",
"throws":"R",
"bats":"R",
"team":"River Cats"
}' | http :3000/api/v1/players
echo '{
"name":"Travis",
"position":"3B",
"throws":"R",
"bats":"L",
"team":"River Cats"
}' | http :3000/api/v1/players
echo '{
"name":"Joe",
"position":"C",
"throws":"L",
"bats":"L",
"team":"Mariners"
}' | http :3000/api/v1/players
GET
Retrieve a record from the database
Example
After populating the database with the example POST
requests, make the following GET
request using HTTPie:
http :3000/api/v1/teams
It should output something like the following:
{
"count": 2,
"results": [
{
"__v": 0,
"_id": "5d641ed242090562206ed463",
"id": "5d641ed242090562206ed463",
"name": "River Cats",
"players": [
{
"__v": 0,
"_id": "5d641fc442090562206ed465",
"bats": "R",
"name": "Billy",
"position": "1B",
"team": "River Cats",
"throws": "R"
},
{
"__v": 0,
"_id": "5d641fc442090562206ed466",
"bats": "L",
"name": "Travis",
"position": "3B",
"team": "River Cats",
"throws": "R"
}
]
},
{
"__v": 0,
"_id": "5d641edb42090562206ed464",
"id": "5d641edb42090562206ed464",
"name": "Mariners",
"players": [
{
"__v": 0,
"_id": "5d641fc742090562206ed467",
"bats": "L",
"name": "Joe",
"position": "C",
"team": "Mariners",
"throws": "L"
}
]
}
]
}
PUT
Update an existing record in the database
Example
After populating the database with the example POST
requests, make the following PUT
request using HTTPie to update a document:
echo '{
"name":"Dude"
}' | http PUT :3000/api/v1/players/<PLAYER_ID>
The server will return the updated document. Something like:
{
"__v": 0,
"_id": "5d641fc442090562206ed465",
"bats": "R",
"name": "Dude",
"position": "1B",
"team": "River Cats",
"throws": "R"
}
DELETE
Remove a record from the database
Example
After populating the database with the example POST
requests, make the following PUT
request using HTTPie to update a document:
echo '{
"name":"Dude"
}' | http PUT :3000/api/v1/players/<PLAYER_ID>
The server will return the updated document. Something like:
{
"__v": 0,
"_id": "5d641fc442090562206ed465",
"bats": "R",
"name": "Dude",
"position": "1B",
"team": "River Cats",
"throws": "R"
}
Deployment
You can quickly deploy your own version with Heroku using this button.