golang-saas-starter-kit/cmd/web-api

SaaS Web API

Copyright 2019, Geeks Accelerator
twins@geeksaccelerator.com

Description

Web API is a client facing API. Standard response format is JSON. The example web-api service includes API documentation.

While the web app is meant for humans to experience and requires a friendly UI, the web API is meant for customers or third-party partners of your SaaS to programmatically integrate. To help show the similarities and differences between the pages in the web app and similar endpoints in the web API, we have created this diagram below. Since it is very detailed, you can click on the image to see the larger version.

This web-api service is not directly used by the web-app service to prevent locking the functionally required for internally development of the web-app service to the same functionality exposed to clients via this web-api service. This separate web-api service can be exposed to clients and be maintained in a more rigid/structured process to manage client expectations.

Not all CRUD methods are exposed as endpoints. Only endpoints that clients may need should be exposed. Internal services should communicate directly with the business logic packages or a new API should be created to support it. This separation should help decouple client integrations from internal application development.

Making Requests to Web API

Once the web-api service is running it will be available on port 3001. http://127.0.0.1:3001/

The easiest way to make requests to the web-api service is by using CURL via your CLI.

To make a request to the web-api service you must have an authenticated user. Users can be created with the API but an initial admin user must first be created. The initial admin user can easily be created using the Swagger API documentation.

API Documentation

Documentation for this API service is automatically generated using swag. The Swag Go project also provides a web UI to allow you and your customers of your SaaS to explore your API - its exposed business logic - as well as easily try our that exposed functionality.

Once this web-api service is running, the Swagger API documentation for the service can be accessed at /docs: http://127.0.0.1:3001/docs/

You can refer to the example of the API documentation that we have deployed on production for you here: https://api.example.saasstartupkit.com/docs/

Local Installation

Build

go build .

Docker

To build using the docker file you need to be in the project root directory. The Dockerfile assumes the working context is the root directory since it references Go Module files to build the image.

docker build -f cmd/web-api/Dockerfile -t saas-web-api .

Getting Started

1. Ensure dependant services are running.

Navigate to the project root where docker-compose.yaml exists. There is only one docker-compose.yaml file that is shared between all services.

Start Services.

docker-compose up -d 

1.1. Set env variables.

Copy the sample file to make your own copy:

cp sample.env local.env

Make any changes to your copy of the file if necessary and then add them to your env:

source local.env

1.2. Start the web-api service.

Invoke main.go directly or use go build .:

go run main.go

2. Initialize the MySQL database.

When docker-compose up is first ran, as discussed in the main readme, the database is created but does not include any schema.

Thus, you need to use the project's schema tool to initialize the database. To do this navigate to the tools/schema folder. Add the source to your env. Then run the main.go file for schema.

cd tools/schema/
source sample.env 
go run main.go 

Notice that if you run main.go again, you should see in the output than all migrations already ran (as expected).

3. Open the Swagger UI.

Navigate your browser to http://127.0.0.1:3001/docs.

4. Signup a new account.

Find the signup endpoint in the Swagger UI.

Click Try it out. Example data has been pre-populated to generate a valid POST request. Your can adjust the values for the account and user objects accordingly.

{
  "account": {
    "address1": "221 Tatitlek Ave",
    "address2": "Box #1832",
    "city": "Valdez",
    "country": "USA",
    "name": "Company 895ff280-5ed9-4b09-b7bc-86ab0f0951d4",
    "region": "AK",
    "timezone": "America/Anchorage",
    "zipcode": "99686"
  },
  "user": {
    "email": "90873f61-663e-43d1-8f0c-00415e73f650@example.com",
    "name": "Gabi May",
    "password": "SecretString",
    "password_confirm": "SecretString"
  }
}

Note the user email and password from the above request will be used in the following steps.

Click Execute and a response with status code 201 should have been returned.

{
  "account": {
    "id": "baae6e0d-29ae-456f-9648-44c1e90ca8af",
    "name": "Company 895ff280-5ed9-4b09-b7bc-86ab0f0951d4",
    "address1": "221 Tatitlek Ave",
    "address2": "Box #1832",
    "city": "Valdez",
    "region": "AK",
    "country": "USA",
    "zipcode": "99686",
    "status": "active",
    "timezone": "America/Anchorage",
    "signup_user_id": {
      "String": "bfdc5ca9-872c-4417-8030-e1b4962a107c",
      "Valid": true
    },
    "billing_user_id": {
      "String": "bfdc5ca9-872c-4417-8030-e1b4962a107c",
      "Valid": true
    },
    "created_at": "2019-06-25T11:00:53.284Z",
    "updated_at": "2019-06-25T11:00:53.284Z"
  },
  "user": {
    "id": "bfdc5ca9-872c-4417-8030-e1b4962a107c",
    "name": "Gabi May",
    "email": "90873f61-663e-43d1-8f0c-00415e73f650@example.com",
    "timezone": "America/Anchorage",
    "created_at": "2019-06-25T11:00:53.284Z",
    "updated_at": "2019-06-25T11:00:53.284Z"
  }
}

If successful, data should be returned for code 201 for created.

Now you will now be able to use the email and password credentials to generate an auth token with the web-api service.

Note: if Swagger Try it out response is TypeError: Failed to fetch, you probably accesed the swagger webpage via http://localhost:3001/docs. This would lead to a CORS error. You should open http://127.0.0.1:3001/docs

5. Generate an Auth Token

An auth token is required for all other requests.

Near the top of the Swagger UI locate the button Authorize and click it.

Find the section OAuth2Password (OAuth2, password)

In username and password field fill the email value and password used in the signup process respectively. Be careful that Swagger UI generates a random email in the signup process, it isn't the same as in section 4.

Click the button Authorize to generate a token that will be used by the Swagger UI for all future requests.

6. Test Auth Token

Now that the Swagger UI is authorized, try running endpoint using the oauth token.

Find the endpoint GET /accounts/{id} endpoint in the Swagger UI.

Click Try it out and enter the account ID from generated from signup (step 5).

Click Execute. The response should be of an Account.

Authenticating Directly with Web API

If you want to authenticate directly with this web-api service and not via the Swagger UI, use the following steps.

1. Authenticating

Before any authenticated requests can be sent you must acquire an auth token. Make a request using HTTP Basic auth with your email and password to get an auth token.

curl --user "twin@example.com:SecretString" -X POST http://127.0.0.1:3001/v1/oauth/token

It is best to put the resulting token in an environment variable like $TOKEN. Notice that security tokens have an expiry date.

####2. Adding Token as Environment Variable

export TOKEN="COPY TOKEN STRING FROM LAST CALL"

####3. Authenticated Requests

To make authenticated requests put the token in the Authorization header with the Bearer prefix.

curl -H "Authorization: Bearer ${TOKEN}" http://127.0.0.1:3001/v1/users

Update Swagger API Documentation

Documentation is generated using swag

If you are developing this web-api service and you want your changes reflected in the API documentation, you will need to download Swag and then run it each time you want the API documentation to be updated.

Download Swag with this command:

go get -u github.com/geeks-accelerator/swag/cmd/swag

Run swag init in the service's root folder which contains the main.go file. This will parse your comments and generate the required files (docs folder and docs/docs.go).

swag init

Additional Swagger Annotations

Below are some additional example annotations that can be added to main.go

// @title SaaS Example API
// @description This provides a public API...
// @termsOfService http://example.com/terms

// @contact.name API Support
// @contact.email support@geeksinthewoods.com
// @contact.url http://example.com/support

Troubleshooting Swag

If you run into errors running swag init try the following:

cannot find package

Try to install the packages to your $GOPATH.

GO111MODULE=off go get -u github.com/leodido/go-urn
GO111MODULE=off go get -u github.com/lib/pq/oid
GO111MODULE=off go get -u github.com/lib/pq/scram
GO111MODULE=off go get -u github.com/tinylib/msgp/msgp
GO111MODULE=off go get -u gopkg.in/DataDog/dd-trace-go.v1/ddtrace
GO111MODULE=off go get -u golang.org/x/xerrors

error writing go.mod

Need to update pkg directory permissions.

Full error:

error writing go.mod: open /Users/leebrown/go/pkg/mod/github.com/lib/pq@v1.1.1/go.mod691440060.tmp: permission denied

Ensure the pkg directory used for go module cache has the correct permissions.

sudo chown -R $(whoami):staff ${HOME}/go/pkg
sudo chmod -R 755 ${HOME}/go/pkg