JSON Serverless

• Architecture
• Features
• Quickstart
• Customization
• Used Packages
• Components
• Develop and debug locally
• Develop locally with cloud resources
• Diagnose issues

Architecture

Features

• Easily generate routes and resources for the Api via json-server
• New: Added CLI
• 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. Install Solution

npm i -g json-serverless

2. Run local

1. create a jsonserver-file sample e.g. db.json

   {
       "posts": [
         { "id": 1, "title": "json-server", "author": "typicode" },
         { "id": 2, "title": "test", "author": "yourAuthor" }
       ],
       "comments": [
         { "id": 1, "body": "some comment", "postId": 1 }
       ],
       "profile": { "name": "typicode" }
   }
   

2. execute command

   jsonsls run db.json
   

3. Deploy api to AWS

1. Verify that you have a AWS account and set appropriate credentials

2. execute command

   jsonsls create-stack db.json {optional: STAGE}

• a stack template folder will be created that contains the deployable serverless framework solution. You can use the serverless cli in this stack template folder.

• When the deployment was successful you can see following output

  
  Service Information
  service: serverless-json-server
  stage: dev
  region: eu-central-1
  stack: serverless-json-server-dev
  api keys:
    serverless-json-server.dev: {API-KEY}
  endpoints:
    ANY - https://xxxxxx.execute-api.eu-central-1.amazonaws.com/dev/ <== {ENDPOINTURL}
    ANY - https://xxxxxxx.eu-central-1.amazonaws.com/dev/{proxy+}
  functions:
    app: serverless-json-server-dev-app
  layers:
    None
  Serverless: Removing old service artifacts from S3...
  

4. 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

1. replace the url with the url provided by serverless (see above)
2. replace the {API-KEY} with the key you get from serverless (see above)
3. 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

1. update local db.json file in root directory with new values

2. re-deploy the stack via serverless framework

    jsonsls update-stack

3. delete db.json file in S3 Bucket

4. 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

Adapt settings

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
enableJSONValidation	validate JSON file at start	boolean	true

Used Packages

• json-server
• serverless framework
• serverless http
• lowdb-adapter-aws-s3

Components

• NodeJS 10
• AWS API Gateway
• AWS Lambda
• AWS S3

Further Development

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

Start solution

make start-test

Test your API

With Swagger

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

With Curl

1. replace the url with the url provided by serverless (see above)
2. replace the {API - KEY} with the key you get from serverless (see above)
3. 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

FAQ

Cannot use Swagger UI when enableApiKeyAuth is true

The apiKey is set in AWS API Gateway. This means all requests (even the standard route) need to use the API-KEY.

If you want to see the Swagger UI you need to add a plugin e.g. ModHeader to Chrome and add the needed headers:

• Content-Type: application/json
• x-api-key: {provided by sls info in the output after deployment}

I forgot the API-KEY I have set

Ensure you have credentials for AWS set.

sls info

Destroy the stack in the cloud

sls remove

I deployed the solution but I get back a http 500 error

Check Cloudwatch Logs in AWS - the issue should be describe there. Log has the same name as the stack that has been created.