Simple REST API

A proof of concept of a simple REST API in Golang.

All data is held in memory, all transfer is via JSON.

All testing can be with curl or Swagger - although Postman should work too.

Features

• uses the excellent Gorilla MUX
• returns appropriate HTTP status codes
• modify Person method implemented
• uses JSON

In Firefox at least, specifying "application/json" allows interpretation of the JSON:

Installation

• Go is required (version 1.7 or later)

Fetch this project as follows:

$ go get -u github.com/mramshaw/Simple-REST-API

This could also be done with git of course:

$ git clone https://github.com/mramshaw/Simple-REST-API.git

Any dependencies will be fetched in the build process.

Building

• make is required

This will fetch all dependencies, build, and run the executable:

$ make

Local dependencies are stored in a local api directory.

All other dependencies will be stored in a local go directory.

Unit Tests

• make is required

This will run the unit tests for the DAO (api/people package):

$ make test

The unit tests will be run in verbose mode.

Usage

Build and run everything:

$ make

Or run the go code (Ctrl-C to terminate):

$ PORT=8100 CORS_HOST=http://localhost:3200 go run RestfulGorillaMux.go

[Specifying CORS_HOST allows the swagger-ui to function.]

Or run the executable (Ctrl-C to terminate):

$ PORT=8100 CORS_HOST=http://localhost:3200 ./RestfulGorillaMux

The API will then be accessible at:

http://localhost:8100/v1/people

[Note that the API is versioned (which is probably a best practice).]

Testing

Use the following curl commands to test (or use the Swagger UI as shown below).

GET (All):

$ curl -v localhost:8100/v1/people

GET (Individual):

$ curl -v localhost:8100/v1/people/5

$ curl -v localhost:8100/v1/people/1

POST (Create):

$ curl -v -X POST -H "Content-Type: application/json"   \
       -d '{"firstname":"Tommy","lastname":"Smothers"}' \
       localhost:8100/v1/people/5

PUT (Update):

$ curl -v -X PUT -H "Content-Type: application/json" \
       -d '{"firstname":"Tom","lastname":"Smothers","address":{"city":"Hollywood","state":"CA"}}' \
       localhost:8100/v1/people/5

DELETE (Delete):

$ curl -v -X DELETE -H "Content-Type: application/json" \
       localhost:8100/v1/people/5

[Specifying -v shows the HTTP status codes; this can be omitted if the status codes are not of interest.]

Swagger

Although Postman is pretty nice, I've always found Swagger to be a better experience.

The content can be served from swagger-ui (which uses node and npm).

On linux, CORS (Cross Origin Resource Sharing) may be temporarily disabled for chromium as follows:

$ chromium-browser --disable-web-security --user-data-dir

[This will only work if chromium is NOT running, as it will otherwise share the browser session.]

To Do

• Return appropriate HTTP status codes
• Implement code to modify a Person
• Modify to use JSON
• Implement API versioning
• Add a SWAGGER definition
• Implement CORS (Cross Origin Resource Sharing) handling
• Refactor data access into a DAO module
• Add tests for the DAO
• Add a health check
• Refactored code
• Refactor code to NOT use Gorilla/mux
• Move configuration to environment variables (12-Factor everything)
• Make CORS hosts configurable
• Implement graceful shutdown (available since Go 1.8)
• Implement continuous integration (Travis CI)
• Implement code coverage statistics (Codecov.io)
• Implement Go report card (Goreportcard.com)
• Implement SemVer 2.0.0. release tagging
• Add link for Simple-REST-API GoDoc
• Add Prometheus-style instrumentation
• Implement method-based Basic AUTH
• Implement a persistent back-end
• Investigate upgrading to HTTP2
• Upgrade to latest release of Golang (1.14 as of the time of writing)
• Upgrade release badge to conform to new Shields.io standards

Credits

Inspired by, but since heavily mutated, this great tutorial by Nic Raboy:

https://www.thepolyglotdeveloper.com/2016/07/create-a-simple-restful-api-with-golang/

There is also a YouTube video (which is linked to from the article).