Serverless FizzBuzz API
This project is a FizzBuzz game implementation using serverless pattern.
Installation/deployment instructions
Depending on your preferred package manager, follow the instructions below to deploy your project.
Using NPM
- Run
npm i
to install the project dependencies - Run
npx sls deploy
to deploy this stack to AWS
Using Yarn
- Run
yarn
to install the project dependencies - Run
yarn sls deploy
to deploy this stack to AWS
Test your service
This project contains a single lambda function triggered by an HTTP request made on the provisioned API Gateway REST API /fizzbuzz
route with POST
method. The request body must be provided as application/json
.
- requesting
/fizzbuzz
without a validX-Api-Key
header will result in API Gateway returning a403
HTTP error code. - sending a
POST
request to/fizzbuzz
with a payload not containing a number property namednumber
and greater than 0 will result in API Gateway returning a400
HTTP error code. - sending a
POST
request to/fizzbuzz
with a payload containing a number property namednumber
will result in API Gateway returning a200
HTTP status code with aresult
being either "fizzbuzz", "fizz", "buzz" or thenumber
from request.
⚠️ The deployed service requires an API Key to execute the lambda through API Gateway.
Locally
In order to test the fizzbuzz function locally, run the following command:
npx sls invoke local -f hello --path src/functions/hello/mock.json
if you're using NPMyarn sls invoke local -f hello --path src/functions/hello/mock.json
if you're using Yarn
Check the sls invoke local command documentation for more information.
Or using serverless-offline
plugin to serve it locally (Test your requests against http://localhost:3000):
npm start
if you're using NPMyarn start
if you're using Yarn
Remotely
Copy and replace your url
- found in Serverless deploy
command output - and name
parameter in the following curl
command in your terminal or in Postman to test your newly deployed application.
curl --location --request POST 'https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev/fizzbuzz' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: {SERVICE_API_KEY}'
--data-raw '{
"number": 22
}'
Project features
Cloud deployment structure
The project was developed using many AWS core services, like:
Lambda
- Functions to handle business logicAPI Gateway
- Service to handle HTTP connections and trigger lambda functionsCloudwatch
- Monitoring service for API Gateway and lambda usage (logs)X-Ray
- For debugging, it tracks requests end-to-end and represent it in a visual and dynamic way
And it's organized in the following way:
Project structure
The project code base is mainly located within the src
folder. This folder is divided in:
functions
- containing code base and configuration for your lambda functionslibs
- containing shared code base between your lambdas
.
├── src
│ ├── functions # Lambda configuration and source code folder
│ │ ├── fizzbuzz
│ │ │ ├── factory # `FizzBuzz` factory functions to create resources
│ │ │ ├── mock # `FizzBuzz` lambda input parameters, if any, for local invocation
│ │ │ ├── app.ts # `FizzBuzz` express app and middlewares definition
│ │ │ ├── handler.ts # `FizzBuzz` lambda http server adapter creation
│ │ │ ├── helpers.ts # `FizzBuzz` common functions to help handle requests
│ │ │ ├── routes.ts # `FizzBuzz` express routes definition and handlers mapping
│ │ │ ├── service.ts # `FizzBuzz` service layer definition for business logic
│ │ │ └── validation.ts # `FizzBuzz` lambda input event JSON-Schema for validation
│ │ │
│ │ └── index.ts # Import/export of all lambda configurations
│ │
│ └── libs # lambda shared code
│ ├── adapters # external libraries adapter for common usage
│ ├── helpers # common helper functions
│ ├── middlewares # common middlewares
│ └── protocols # interfaces definitions for lambda functions
│
├── package.json
├── serverless.ts # Serverless service file
├── tsconfig.json # Typescript compiler configuration
└── tsconfig.paths.json # Typescript paths
3rd party libraries
- express - used to handle http requests from AWS API Gateway
- serverless-http - used to adapt serverless framework with an http server application
- celebrate - express middleware function to validate incoming requests
- @serverless/typescript - provides up-to-date TypeScript definitions for your
serverless.ts
service file