Json-serverless-lib NPM

JSON Serverless

Architecture

Features

Easily generate routes and resources for the Api via (json-server)
New: Added Swagger UI support
Deployment:
- Deployed in AWS cloud within Minutes by a single command
- Almost zero costs (First million requests for Lambda are free)
- Less maintenance as the deployed solution runs serverless
Security:
- Secured with https by default.
- Optional: Use a generated API Key
Customization:
- This solution written in Typescript can be easily extended for additional enhanced scenarios
  - adding user authentication
  - own custom domain
  - additional routes etc.
- Develop and debug solution locally in Visual Studio Code

Quickstart

1. Clone Solution

git clone https://github.com/pharindoko/json-serverless.git
cd json-serverless

2. Install dependencies

npm install -g serverless
npm i

3. Verify AWS Access / Credentials

=> You need to have access to AWS to upload the solution.

aws sts get-caller-identity

4. Update db.json file in root directory

Root properties marked in bold are the generated endpoints of the API (route generation and json validation is done via json-server)

5. Deploy via Serverless Framework

# set --stage parameter for different stages
serverless deploy --stage dev

serverless-webpack is used
the build will be triggered automatically

6. When the deployment with serverless framework was successful you can see following output

7. Test your Api

With Swagger

Open the {ENDPOINTURL}: https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/ that you received as output

MIND: If you have set enableApiKeyAuth to true => SwaggerUI )

With Curl

replace the url with the url provided by serverless (see above)
replace the {API-KEY} with the key you get from serverless (see above)
replace {route} at the end of the url e.g. with posts (default value)

Default Schema:

Default route is posts: (see db.json)
curl -H "Content-Type: application/json" https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api/posts

# or another route given in db.json file
curl -H "Content-Type: application/json" https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api/{route}

# with enableApiKeyAuth=true
curl -H "x-api-key: {API-KEY}" -H "Content-Type: application/json" https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api/{route}

What`s my {route} ? -> see json-server documentation

Customization

Update content of db.json

update local db.json file in root directory with new values
re-deploy the stack via serverless framework
```
 sls deploy
```
delete db.json file in S3 Bucket
Make a GET request against the root url https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api

curl -H "Content-Type: application/json" https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api

# with enableApiKeyAuth=true
curl -H "x-api-key: {API-KEY}" -H "Content-Type: application/json" https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api/{route}

=> With the next request a new db.json file will be created in the S3 Bucket

Change Stackname

edit service property in serverless.yml (in root directory)

Adapt settings in config/appconfig.yml file

Attribute	Description	Type	Default
readOnly	Make API readonly - all API - write operations are forbidden (http 403))	string	false
enableSwagger	Enable swagger and swagger UI support	string	true
enableApiKeyAuth	Make your routes private by using an additional ApiKey	boolean	false
jsonFile	path of json file that will be used	string	db.json
enableJSONValidation	validate JSON file at start	boolean	true

Used Packages

Components

Develop and debug locally

db.json file will be loaded directly from your local filesystem. No AWS access is needed.

Start solution

npm run start

Debug solution

If you want to debug locally in VS Code everything is already setup (using webpack with sourcemap support)

npm run debug

Test your API

With Swagger

Open the {ENDPOINTURL}: http://localhost:3000/ that you received as output

With Curl

replace the url with the url provided by serverless (see above)
replace the {API - KEY} with the key you get from serverless (see above)
replace {route} at the end of the url e.g. with posts (default value)

Default Schema:

Default route is posts: (see db.json)
curl -H "Content-Type: application/json" http://localhost:3000/api/posts

#or another route given in db.json file
curl -H "Content-Type: application/json" http://localhost:3000/api/{route}

What`s my {route} ? -> see json-server documentation

Develop locally with cloud resources

Use same components (S3, LowDB) as the lambda does but have code executed locally.

1. Add .env file to root folder

Mind: If you haven`t deployed the solution yet, please create a private S3-Bucket and .json - file manually or deploy the solution first to AWS via serverless framework Mind: This function requires that you have access to AWS (e.g. via credentials)

Copy the .env file from .env.sample in the root folder

cp .env.sample .env

Required: Adapt settings in .env file

Attribute	Description	Type	Default
S3File	JSON file used as db to read and write (will be created with a default json value - customize in db.json)	string	db.json
S3Bucket	S3-Bucket - this bucket must already exist in AWS	string	json-server-less-lambda-dev
readOnly	all API - write operations are forbidden (http 403))	boolean	false

2. Start solution

npm run dev

3. Test your API

With Swagger

Open the {ENDPOINTURL}: http://localhost:3000/ that you received as output

With Curl

replace the url with the url provided by serverless (see above)
replace the {API - KEY} with the key you get from serverless (see above)
replace {route} at the end of the url e.g. with posts (default value)

Default Schema:

Default route is posts: (see db.json)
curl -H "Content-Type: application/json" http://localhost:3000/api/posts

# or another route given in db.json file
curl -H "Content-Type: application/json" http://localhost:3000/api/{route}

# with enableApiKeyAuth=true
curl -H "x-api-key: {API-KEY}" -H "Content-Type: application/json" https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/api/{route}

What`s my {route} ? -> see json-server documentation

Diagnose issues

serverless-offline will help you to troubleshoot issues with the lambda execution in a fast manner.

Mind: The assumption is that the solution has been already deployed Mind: This function requires that you have access to AWS (e.g. via credentials)