aws-restful-api

README

A Simple Golang AWS Restful API

This package, which is developed in Golang, implements two simple HTTP request (POST, GET) on Amazon Web Services (AWS) in order to put an item in DynamoDB table through POST request, as well as fetch information about and specific item from DynamoDB table (if exists) via GET request. The package applies AWS Lambda function to interact with AWS interface.

API Request Type

The API accepts the following JSON requests and produces the corresponding HTTP responses:

Request 1

POST request to insert a new device to DynamoDB database

HTTP Method: POST
URL: https://<api-gateway-url>/api/devices
content-type: application/json
Body:
  {
    "id": "/devices/id1",
    "deviceModel": "/devicemodels/id1",
    "name": "Sensor",
    "note": "Testing a sensor.",
    "serial": "A020000102"
  }

Request 2

GET request to fetch a device information based on provided ID

HTTP Method: GET
URL: https://<api-gateway-url>/api/devices/{desired_id}

Prerequisites

The package applies different tech stacks which needs to be installed before running the code. The prerequisites includes:

• Python 3.x
• GO programming language
• AWS CLI
• Go Dep (Dependency management tool)
• NodeJS
• Serverless
• Git

Installation

Much of the installation part is organized based of the Windows platform. First of all you should install Python 3.x and Git if you don't have already.

Install AWS CLI

If you already have installed pip, you can install the AWS CLI (Command Line Interface) using the following command:

$ pip install awscli --upgrade --user

Then you can configure AWS CLI with your credentials and region information:

$ aws configure

Install Golang

Install Golang and then set GOPATH and GOBIN in environment variables.

Install Go Dep

curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh

Install Serverless

First, you need to install NodeJs and then begin to install serverless using following command:

npm install -g serverless

You can verify the installation using:

serverless --version

Project Directories

• device : This directory contains a package which implements the structure of items (device) we can put or fetch from our DynamDB table.

• getDevice : This directory includes two files in order to implement GET request in real world tests. The get.go file implements the main functions for fetching information of a device from DynamoDB table if it exists in the table. The get_test.go includes integration test which uses to test the code in real world.

• postDevice : It is used to implement POST request in real world tests. The post.go file includes the main functions for putting a device into DynamoDB table. The post_test.go includes integration test which is used to test POST request in real world.

• unitTest : unitTest includes codes used to implement mock test of codes. It contains two subdirectories: getDevice & postDevice. These two subdirectories are like previous one with some differences in their get_test.go and post_test.go files in order to mock the output of GET and POST requests respectively.

• Makefile : which is necessary to compile the project.

• serverless.yml : The core component which contains all configurations to deploy this project on AWS.

Build

You have to clone the repository to %GOPATH%/src directory since it imports device struct base on its relative path, otherwise the compiler will raise an error. Then build the project using the following command:

cd %GOPATH%/src/aws-restful-api
make build

❗❗ Note that you have to add the following command at the end of ~/.bashrc of git bash in Windows or Unix-based systems to add TABLE_NAME and its corresponding value as an environment variable.

vim ~/.bashrc
export TABLE_NAME="aws-challenge-devices"

Another option to do this task if you don't want to manipulate your ~/.bashrc is that each time you open a new terminal in Unix-based systems or git bash in Windows, you have to execute following commands in order to export TABLE_NAME as environment variable:

export TABLE_NAME=aws-challenge-devices

Deploy

Deploy the project to AWS using following command:

sls deploy

This command will give two URLs as endpoints for each request in the output.

Unit Test

In order to run unit tests for each request, you should navigate to its corresponding directory in unitTest folder and run the test command. Remember to export TABLE_NAME before executing the test command.

For unit test of POST request:

cd unitTest/postDevice
go test -v

For unit test of GET request:

cd unitTest/getDevice
go test -v

Integration Test

In order to test the code in real world (integration test) on AWS DynamoDB database (given endpoints), run the test files located in postDevice or getDeivce of main project directory. Thus, you should execute following command in terminal or git bash:

For integration test of POST request:

cd postDevice/
go test -v

For integration test of GET request:

cd getDevice/
go test -v

Author

Mohammad Mojrian - AWS Serverless Restful API