Go RESTful API
A Restful API based
Thanks to github.com/qiangxue/golang-restful-starter-kit
Getting Started
If this is your first time encountering Go, please follow the instructions to install Go on your computer. The kit requires Go 1.5 or above.
After installing Go, run the following commands to download and install this starter kit:
# install the starter kit
go get github.com/qiangxue/golang-restful-starter-kit
# install glide (a vendoring and dependency management tool), if you don't have it yet
go get -u github.com/Masterminds/glide
# fetch the dependent packages
cd $GOPATH/qiangxue/golang-restful-starter-kit
make depends # or "glide up"
Next, create a PostgreSQL database named go_restful
and execute the SQL statements given in the file testdata/db.sql
.
The starter kit uses the following default database connection information:
- server address:
127.0.0.1
(local machine) - server port:
5432
- database name:
go_restful
- username:
postgres
- password:
postgres
If your connection is different from the above, you may modify the configuration file config/app.yaml
, or
define an environment variable named RESTFUL_DSN
like the following:
postgres://<username>:<password>@<server-address>:<server-port>/<db-name>
For more details about specifying a PostgreSQL DSN, please refer to the documentation.
Now you can build and run the application by running the following command under the
$GOPATH/qiangxue/golang-restful-starter-kit
directory:
go run server.go
or simply the following if you have the make
tool:
make
The application runs as an HTTP server at port 8080. It provides the following RESTful endpoints:
GET /ping
: a ping service mainly provided for health check purposePOST /v1/auth
: authenticate a userGET /v1/artists
: returns a paginated list of the artistsGET /v1/artists/:id
: returns the detailed information of an artistPOST /v1/artists
: creates a new artistPUT /v1/artists/:id
: updates an existing artistDELETE /v1/artists/:id
: deletes an artist
For example, if you access the URL http://localhost:8080/ping
in a browser, you should see the browser
displays something like OK v0.1#bc41dce
.
If you have cURL
or some API client tools (e.g. Postman), you may try the following more complex scenarios:
# authenticate the user via: POST /v1/auth
curl -X POST -H "Content-Type: application/json" -d '{"username": "demo", "password": "pass"}' http://localhost:8080/v1/auth
# should return a JWT token like: {"token":"...JWT token here..."}
# with the above JWT token, access the artist resources, such as: GET /v1/artists
curl -X GET -H "Authorization: Bearer ...JWT token here..." http://localhost:8080/v1/artists
# should return a list of artist records in the JSON format