jlucktay's RESTful API (jra)

Description

This is my implementation of a RESTful HTTP API capable of CRUD operations and persisting resource state to a database.

Implementation guidelines

• Follow best practices, for example TDD/BDD, with a focus on full-stack testing.
• Prioritize correctness, robustness, and extensibility over extra features and optimizations.
• Write code with the quality bar one would expect to see in production.
• Try to simplify by using open source frameworks and libraries where possible.

Installation

Prerequisites

You should have a working Go environment and have $GOPATH/bin in your $PATH. Mage is being used for various build/run/test tasks, and should also be installed.

Compiling

To download the source, compile, and install the relevant binaries, run:

go get go.jlucktay.dev/rest-api/...

The source code will be located in $GOPATH/src/go.jlucktay.dev/rest-api.

Newly compiled jra and jrams binaries will be in $GOPATH/bin/.

Mage

The Magefile contains targets for various tasks, which can be listed out with mage -l.

Usage

Launching the API server:

Running with Docker

$ docker-compose up
Starting rest-api_web_1   ... done
Starting rest-api_mongo_1 ... done
Attaching to rest-api_mongo_1, rest-api_web_1
web_1    | Connected to MongoDB!
web_1    | Collection 'payments' contains 0 records.
...

The API server will be listening at http://localhost:8080/v1/.

Running the server directly

$ jra
Connected to MongoDB!
Collection 'payments' contains 0 records.

Seeding the server with some sample records:

$ jrams
Continuing will delete ALL payment records in MongoDB (database: rest-api, collection: payments)
Press 'Enter' to continue, or CTRL+C to cancel...
Connected to MongoDB!
Collection 'payments' contains 14 records.
Collection 'payments' dropped.
Disconnected from MongoDB.
Connected to MongoDB!
Collection 'payments' contains 0 records.
Added payment with ID '4ee3a8d8-ca7b-4290-a52c-dd5b6165ec43'.
...

Accessing the server:

$ curl --silent --request GET http://localhost:8080/v1/payments
{
  "data": [
    {
      "attributes": {
...

Documentation

Here is the full design doc for this API, which describes the various endpoints, how to call them, and what to expect in return.

Testing

There is a Mage target to run tests across all packages in the repo:

$ mage test
?       go.jlucktay.dev/rest-api/cmd/jra    [no test files]
?       go.jlucktay.dev/rest-api/internal/cmd/jrams [no test files]
?       go.jlucktay.dev/rest-api/pkg/org    [no test files]
ok      go.jlucktay.dev/rest-api/pkg/server 0.187s
ok      go.jlucktay.dev/rest-api/pkg/storage        0.262s
?       go.jlucktay.dev/rest-api/pkg/storage/inmemory       [no test files]
?       go.jlucktay.dev/rest-api/pkg/storage/mongo  [no test files]
ok      go.jlucktay.dev/rest-api/test       0.128s

For more details on how Go itself discovers and executes tests, and the various flags with which to alter behaviour when doing so, run go help test and go help testflag.

Roadmap

Features and functionality yet to be implemented are captured in the TODO markdown file in this repo as well as on the Trello board.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT