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:

1. Clone the repository to your machine

2. Navigate to the repository and install all dependencies (listed in the package.json)

   cd api-server basic
   
   npm i
   

3. Create a file named .env in the repository's root directory and add the following variables:

   • PORT - defaults to 3000
   • 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
   

4. 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.