A template for starting projects with express
as an API. Includes
authentication and common middlewares.
- Download this template. (Do not git clone, simply download)
- Move the .zip file to your
wdi/projects/
directory and Unzip it (creating a folder) -- NOTE: if the folder was already unzipped, use themv
command line to move it to thewdi/projects/
directory. - Rename the directory from express-api-template -> your-app-name.
- Empty
README.md
and fill with your own content. - Move into the new project and
git init
. - Replace all instances of
'express-api-template'
with your app name. - Install dependencies with
npm install
.- if this doesn't work then run
npm install --save bcryptjs && npm uninstall --save bcrypt
first then runnpm install
again. (make sure you replace every instance ofrequire('bcrypt')
in your app intorequire('bcryptjs')
- if this doesn't work then run
- Ensure that you have
nodemon
installed by runningnpm install -g nodemon
. - Don't forget to start running
mongod
. - Ensure the API is functioning properly by running
npm run server
. - Once everything is working, make an initial commit.
Follow instructions here
Dependencies are stored in package.json
.
The most important file for understanding the structure of the template is
server.js
. This is where the actual Express app
object is created, where
the middlewares and routes are registered, and more. To register a routefile,
follow the pattern established here with exampleRoutes
and userRoutes
. If
you want to add any middlewares to your app, do that here.
The app
directory contains models and route files. Models are simply Mongoose
models. To create your own, follow the patterns established in
app/models/example.js
. Route files are somewhat similar to controllers in
Rails, but they cover more functionality, including serialization and deciding
which HTTP verbs to accept and what to do with them.
The config
directory holds just db.js
, which is where you specify the name
and URL of your database.
The lib
directory is for code that will be used in other places in the
application. The token authentication code is stored in lib/auth.js
. The
other files in lib
deal with error handling. custom_errors.js
is where all
the different custom classes of errors are created. If you need some other kind
of error message, you can add it here. There are also some functions defined
here that are used elsewhere to check for errors. lib/error_handler.js
is a
function that will be used in all your .catch
es. It catches errors, and sets
the response status code based on what type of error got thrown.
You probably will only need to interact with files in app/models
,
app/routes
, and server.js
. You'll need to edit db/config.js
just once,
to change the name of your app.
Instead of grunt
, this template uses npm
as a task runner. This is more
conventional for modern Express apps, and it's handy because we'll definitely
use npm
anyway. These are the commands available:
Command | Effect |
---|---|
npm run server |
Starts a development server with nodemon that automatically refreshes when you change something. |
npm test |
Runs automated tests. |
npm run debug-server |
Starts the server in debug mode, which will print lots of extra info about what's happening inside the app. |
Use this as the basis for your own API documentation. Add a new third-level heading for your custom entities, and follow the pattern provided for the built-in user authentication documentation.
Scripts are included in curl-scripts
to test built-in actions.
Add your own scripts to test your custom API.
Verb | URI Pattern | Controller#Action |
---|---|---|
POST | /sign-up |
users#signup |
POST | /sign-in |
users#signin |
PATCH | /change-password/ |
users#changepw |
DELETE | /sign-out/ |
users#signout |
Request:
curl --include --request POST http://localhost:4741/sign-up \
--header "Content-Type: application/json" \
--data '{
"credentials": {
"email": "[email protected]",
"password": "an example password",
"password_confirmation": "an example password"
}
}'
curl-scripts/sign-up.sh
Response:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"user": {
"id": 1,
"email": "[email protected]"
}
}
Request:
curl --include --request POST http://localhost:4741/sign-in \
--header "Content-Type: application/json" \
--data '{
"credentials": {
"email": "[email protected]",
"password": "an example password"
}
}'
curl-scripts/sign-in.sh
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"user": {
"id": 1,
"email": "[email protected]",
"token": "33ad6372f795694b333ec5f329ebeaaa"
}
}
Request:
curl --include --request PATCH http://localhost:4741/change-password/ \
--header "Authorization: Token token=$TOKEN" \
--header "Content-Type: application/json" \
--data '{
"passwords": {
"old": "an example password",
"new": "super sekrit"
}
}'
TOKEN=33ad6372f795694b333ec5f329ebeaaa curl-scripts/change-password.sh
Response:
HTTP/1.1 204 No Content
Request:
curl --include --request DELETE http://localhost:4741/sign-out/ \
--header "Authorization: Token token=$TOKEN"
TOKEN=33ad6372f795694b333ec5f329ebeaaa curl-scripts/sign-out.sh
Response:
HTTP/1.1 204 No Content
- All content is licensed under a CCBYNCSA 4.0 license.
- All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact [email protected].