goaddr
A Restful API (and db) for a super simple Address Book written in Golang. Requires Go 1.15 or higher to build.
Getting the app
Go Binaries
The easiest way to access the app is via go
. The following commands will download the executable into your go files and run the API server on port 8080 with an in-memory database:
go get github.com/deversmann/goaddr
goaddr
Container
The latest build of the container can also be found at https://quay.io/repository/deversmann/goaddr and can be pulled using:
podman pull quay.io/deversmann/goaddr
Building locally
Building the application requires go 1.15 or higher. Clone the repository and enter the directory and execute the following:
go mod tidy # downloads the dependencies
go run main.go # runs without building
#or
go build # builds the executable in the working directory
./goaddr # runs from the local directory
# or
go install # builds the executable and installs it in the go binaries directory
goaddr # assumes that go binaries is on your path
The project includes a Containerfile
that can be used to build a container containing the application. To build the container locally:
podman build --tag localhost/goaddr .
The resulting container could be run using:
podman run -d -rm \
-e GOADDR_DBDIALECT="postgresql" \
-e GOADDR_DBDSN="host=192.0.2.42 user=user password=pass dbname=db" \
-e GOADDR_PORT=8081
-p 8081:8081 --name goaddr localhost/goaddr
Configuration
The following attributes can be configured by using environment variables:
Configuration |
ENV Var Name |
Default |
Notes |
Database Dialect |
GOADDR_DBDIALECT |
sqlite |
The type of database being connected to. Currently only sqlite and postgresql are valid options. For sqlite , the service will create the specified db file if it doesn't exist. |
Database DSN |
GOADDR_DBDSN |
file::memory:?cache=shared (in-memory db) |
The connect string for the database selected. See https://gorm.io/docs/connecting_to_the_database.html for examples |
Web Service Port |
GOADDR_PORT |
8080 |
The port the web service will listen on |
Logging Level |
GOADDR_LOGLEVEL |
No Default |
There are only 2 log levels, DEBUG and INFO. By default, only INFO is on. Set to DEBUG to add DEBUG or to NONE to turn off all. |
API Definition
Call |
Success |
Failure |
POST /api/v1/contacts |
201 created |
400 if JSON is not valid |
GET /api/v1/contacts * |
200 OK |
400 if query is not valid 404 if no contacts are found |
GET /api/v1/contacts/:id |
200 OK |
404 if contact with id is not found |
PUT /api/v1/contacts/:id |
202 accepted |
400 if JSON is not valid 404 if contact with id is not found |
DELETE /api/v1/contacts/:id |
204 no content |
404 if contact with id is not found |
Query options
The group GET request has multiple combinable ways of being limited:
Type |
Syntax |
Notes |
Filter |
<field>=<value> |
Does a case-insensitive search for the value in the named field |
Sort |
sort_by=<field1>,-<field2> |
Prepend the field name with '-' for descending sort Should be used for reliable pagination |
Limit |
limit=<number> |
Only returns the first number results Used in conjunction with offset to paginate results |
Offset |
offset=<number> |
Discards the first number results Used in conjunction with limit to paginate results |
Return Values
If an entry is retrieved, created or modified, the api will return a JSON representation of that entry:
{
"id": 1,
"firstname": "Paul",
"lastname": "Cormir",
"address": "100 E. Davie St.",
"city": "Raleigh",
"state": "NC",
"zipcode": "27601",
"phone": "888-RED-HAT-1",
"email": "pcormir@redhat.com"
}
If a collection is requested, the entries are returned in a JSON list:
{
"contacts": [
{
"id": 1,
"firstname": "Paul",
"lastname": "Cormir",
"address": "100 E. Davie St.",
"city": "Raleigh",
"state": "NC",
"zipcode": "27601",
"phone": "888-RED-HAT-1",
"email": "pcormir@redhat.com"
},
...
]
}
If an error occurs, the HTTP error code will be accompanied by a message describing the failure:
{
"message": "Invalid JSON for contact",
"status": 400
}