A REST API Boilerplate written in Go.
- Author(s): John Connor Sanders
- Current Version: 0.0.1
- Release Date: 9/25/2022
- MIT License
Follow the instructions below to get the Go REST API up and running on your local environment
- MongoDB 4+
- Go 1.18+
- Create a conf.json file from the example file and configure the following settings:
- MongoDB URI Connection String
- Secret Encryption String
- Mongo Database Name
- Master Admin Username
- Master Admin Email
- Master Admin Initial Password
- Whether to run App with HTTPS
- If HTTPS is on, the cert.pem file
- If HTTPS is on, the path to the key.pem file
- Whether you want new users to be able to sign themselves up for accounts
- Run ENV
- Use the provided install.sh script to build a background service
$ cp conf.json.example conf.json
$ vi conf.json
One way to set up and start a production build is to run the following:
- Build executable and install the SystemD service:
$ go build github.com/JECSand/go-rest-api-boilerplate
$ sh ./scripts/setup_service.sh
- To start the API:
$ sh ./scripts/start.sh
- To stop the API:
$ sh ./scripts/stop.sh
To start the API in development:
$ go run github.com/JECSand/go-rest-api-boilerplate
To stop the development API, enter 'ctrl + c'
- Integration Test
$ go test github.com/JECSand/go-rest-api-boilerplate/cmd
- Unit Tests
- Test Auth Module:
$ go test github.com/JECSand/go-rest-api-boilerplate/auth
- Test Database Module:
$ go test github.com/JECSand/go-rest-api-boilerplate/database
- Test Models Module:
$ go test github.com/JECSand/go-rest-api-boilerplate/models
- POST - /auth
- Headers
{
Content-Type: application/json
}
- Body
{
"email": "[email protected]",
"password": "userpass"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Auth-Token: "",
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000011",
"username": "userName",
"firstname": "john",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": 000000000000000000000001",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
- POST - /auth/register
- This route will return a 404 if the "Registration" setting is set to "off" in the conf.json file.
- Headers
{
Content-Type: application/json
}
- Body
{
"firstname": "john",
"lastname": "smith",
"email": "[email protected]",
"password": "789xyz",
"username": "userName",
"password": "userpass"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Auth-Token: "",
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000012",
"username": "userName",
"firstname": "john",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"groupuuid": "000000000000000000000002",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
- GET - /auth
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Auth-Token: "",
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- DELETE - /auth
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- GET - /auth/api-key
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Auth-Token: "",
API-Key: "",
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- POST - /auth/password
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Body
{
"current_password": "current_password",
"new_password": "new_password"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- GET - /tasks
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"tasks": [
{
"id": "000000000000000000000021",
"name": "todo_name",
"due": 2019-08-01 12:04:01 -0000 UTC,
"status": "NOT_STARTED",
"description": "Task to complete",
"user_id": "000000000000000000000011",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:28:09.400248747 +0000 UTC,
"created_at": 2019-06-07 20:28:09.400248747 +0000 UTC
}
]
}
- GET - /tasks/{taskId}
- todoId parameter is optional, if used the request will only return an object for that item.
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000021",
"name": "todo_name",
"due": 2019-08-01 12:04:01 -0000 UTC,
"status": "NOT_STARTED",
"description": "Task to complete",
"user_id": "000000000000000000000011",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:28:09.400248747 +0000 UTC,
"created_at": 2019-06-07 20:28:09.400248747 +0000 UTC
}
- POST - /tasks
- Headers
{
Content-Type: application/json; charset=UTF-8,
Auth-Token: ""
}
- Body
{
"name": "todo_name",
"due": 2019-08-01 12:04:01 -0000 UTC,
"description": "Task to complete"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000021",
"name": "todo_name",
"due": 2019-08-01 12:04:01 -0000 UTC,
"status": "NOT_STARTED",
"description": "Task to complete",
"user_id": "000000000000000000000011",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:28:09.400248747 +0000 UTC,
"created_at": 2019-06-07 20:28:09.400248747 +0000 UTC
}
- PATCH - /tasks/{taskId}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Auth-Token: ""
}
- Body
{
"name": "new_todo_name",
"due": 2019-08-06 12:04:01 -0000 UTC,
"description": "Updated Task to complete",
"status": "COMPLETED",
"user_id": "000000000000000000000011"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000022",
"name": "new_todo_name",
"due": 2019-08-01 12:04:01 -0000 UTC,
"status": "COMPLETED",
"description": "Task to complete",
"user_id": "000000000000000000000011",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:28:09.400248747 +0000 UTC,
"created_at": 2019-06-07 20:28:09.400248747 +0000 UTC
}
- DELETE - /task/{taskId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- GET - /users
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"users": [
{
"id": "000000000000000000000011",
"username": "userName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
]
}
- GET - /users/{userId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000011",
"username": "userName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
- POST - /users
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Body
{
"username": "userName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"password": "xyz789",
"role": "member"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000012",
"username": "userName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
- PATCH - /users/{userId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Body
{
"id": "000000000000000000000012",
"username": "newUserName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"password": "newUserpass",
"role": "member",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000012",
"username": "newUserName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
- DELETE - /users/{userId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- GET - /users/{userId}/tasks
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"user": {
"id": "000000000000000000000012",
"username": "newUserName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
},
"tasks": [
{
"id": "000000000000000000000022",
"name": "task_name",
"status": "NOT_STARTED",
"due": 2019-06-07 20:28:09.400248747 +0000 UTC,
"description": "Task to complete",
"user_id": "000000000000000000000012",
"group_id": "000000000000000000000001",
"last_modified": 2019-06-07 20:28:09.400248747 +0000 UTC,
"created_at": 2019-06-07 20:28:09.400248747 +0000 UTC
}
]
}
- GET - /groups
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"groups": [
{
"id": "000000000000000000000001",
"name": "groupName",
"last_modified": 2019-06-07 20:17:14.358617998 +0000 UTC,
"creation_datetime": 2019-06-07 20:17:14.358617998 +0000 UTC
}
]
}
- GET - /groups/{groupId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000001",
"name": "groupName",
"last_modified": 2019-06-07 20:17:14.358617998 +0000 UTC,
"creation_datetime": 2019-06-07 20:17:14.358617998 +0000 UTC
}
- POST - /groups
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Body
{
"name": "newGroup"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000002",
"name": "newGroup",
"last_modified": 2019-06-07 20:18:15.145971952 +0000 UTC,
"creation_datetime": 2019-06-07 20:18:15.145971952 +0000 UTC
}
- PATCH - /groups/{groupId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Body
{
"Name": "newGroupName"
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"id": "000000000000000000000002",
"name": "newGroup",
"last_modified": 2019-06-07 20:18:15.145971952 +0000 UTC,
"creation_datetime": 2019-06-07 20:18:15.145971952 +0000 UTC
}
- DELETE - /groups/{groupId}
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- GET - /groups/{groupId}/users
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"group": {
"id": "000000000000000000000002",
"name": "newGroup",
"last_modified": 2019-06-07 20:18:15.145971952 +0000 UTC,
"creation_datetime": 2019-06-07 20:18:15.145971952 +0000 UTC
},
"users": [
{
"id": "000000000000000000000011",
"username": "userName",
"firstname": "jane",
"lastname": "smith",
"email": "[email protected]",
"role": "member",
"group_id": "000000000000000000000002",
"last_modified": 2019-06-07 20:17:14.630917778 +0000 UTC,
"created_at": 2019-06-07 20:17:14.630917778 +0000 UTC
}
]
}
- GET - /groups/{groupId}/tasks
- Headers
{
Content-Type: application/json,
Auth-Token: ""
}
- Headers
{
Content-Type: application/json; charset=UTF-8,
Date: DoW, DD MMM YYYY HH:mm:SS GMT,
Content-Length: 0,
Access-Control-Allow-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Expose-Headers: Content-Type, Auth-Token, API-Key,
Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: GET,DELETE,POST,PATCH
}
- Body
{
"group": {
"id": "000000000000000000000002",
"name": "newGroup",
"last_modified": 2019-06-07 20:18:15.145971952 +0000 UTC,
"creation_datetime": 2019-06-07 20:18:15.145971952 +0000 UTC
},
"tasks": [
{
"id": "000000000000000000000022",
"name": "task_name",
"status": "NOT_STARTED",
"due": 2019-06-07 20:28:09.400248747 +0000 UTC,
"description": "Task to complete",
"user_id": "000000000000000000000001",
"group_id": "000000000000000000000002",
"last_modified": 2019-06-07 20:28:09.400248747 +0000 UTC,
"created_at": 2019-06-07 20:28:09.400248747 +0000 UTC
}
]
}