{"id":15654740,"url":"https://github.com/trilom/sls-microservice","last_synced_at":"2025-10-30T11:49:16.809Z","repository":{"id":143815811,"uuid":"186086500","full_name":"trilom/sls-microservice","owner":"trilom","description":"This is an example repository of a skeleton project for an example backend and front end api split into sub directories.","archived":false,"fork":false,"pushed_at":"2019-05-16T20:50:40.000Z","size":143,"stargazers_count":26,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-30T21:05:11.990Z","etag":null,"topics":["framework","microservice","serverless","serverless-framework"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trilom.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-11T04:14:20.000Z","updated_at":"2021-12-19T23:26:55.000Z","dependencies_parsed_at":"2023-12-03T16:15:12.838Z","dependency_job_id":null,"html_url":"https://github.com/trilom/sls-microservice","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trilom%2Fsls-microservice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trilom%2Fsls-microservice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trilom%2Fsls-microservice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trilom%2Fsls-microservice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trilom","download_url":"https://codeload.github.com/trilom/sls-microservice/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251849189,"owners_count":21653829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","microservice","serverless","serverless-framework"],"created_at":"2024-10-03T12:53:46.145Z","updated_at":"2025-10-30T11:49:11.763Z","avatar_url":"https://github.com/trilom.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless Microservice Framework\n\n## Diagram:\n![api diagram](https://github.com/trilom/sls-microservice/blob/master/sls-microservice.jpg \"API Diagram\")\n\n## How to use:\nLike all infrastructure stacks, there is some soft of backend, and frontend.  In this case we have a front end implemented with API Gateway and a simple backend with 2 tables and a SQS queue to trigger a function.  \nIn order to use this stack you simply run the `make buildAll` and `make deployAll` command from within the `./backend` directory.  \n\n## Why is it designed like this:\nIn order to gain fine control over each endpoint of your API this allows you to separate your project into distinct directories to lighten global dependencies.\n\n### What does this build?\n---\nThis will define an example Serverless infrastructure stack containing:\n1. an API Gateway\nThe API has 6 endpoints.  One to create a user, one to get a user information, one to get a list of users, one to get a list of orders for a user, one to get order information for that user, and one to create an order.\n2. two DynamoDB tables\nOne is the user table and one is the order table.\n3. a SQS queue\nAn SQS queue that looks out for orders and moves them to fulfillment.\n4. one backend lambda function, and three api lambda functions\nThe backend function will look for messages in the Order queue, then move them to fulfillment.\nThe API functions are split into 3 endpoints where you can implement different packages scope.\n\n#### Endpoints\n---\n`/user` __GET__ - _List of users._  \n`/user` __POST__ - _Create a user._  \n`/user/{userid}` __GET__ - _User information._  \n`/user/{userid}/orders` __GET__ - _Get order information for user._  \n`/order` __POST__ - _Create an order._  \n`/order/{orderid}` __GET__ - _Get order information._  \n\n### Things to note\n#### API Gateway RestApiId Exports and Usage\n---\nTake note in the `./backend/serverless.yml` we are exporting two variables from the stack.  This is for reuse in our child API endpoint stacks:\n```yaml\n#export from ./backend/serverless.yml\n- Outputs:\n    ApiGWRestApiId:\n      Value:\n        Ref: ApiGatewayRestApi\n      Export:\n        Name: ${self:custom.${self:provider.stage}.Stack}-restApiId-${self:provider.stage}\n    ApiGWRootResourceId:\n      Value:\n        Fn::GetAtt:\n          - ApiGatewayRestApi\n          - RootResourceId\n      Export:\n        Name: ${self:custom.${self:provider.stage}.Stack}-rootResourceId-${self:provider.stage}\n```\n```yaml\n#import from ./api/src/user/serverless.yml\nprovider:\n  ...\n  apiGateway:\n    restApiId:\n      'Fn::ImportValue': ${self:custom.${self:provider.stage}.Stack}-restApiId-${self:provider.stage}\n    restApiRootResourceId:\n      'Fn::ImportValue': ${self:custom.${self:provider.stage}.Stack}-rootResourceId-${self:provider.stage}\n```\n\n__Special Consideration:__ When nesting resources within other resources, for example we have the API endpoint of `/user/{userid}/orders`.  This endpoint is served separately from our `/user` endpoint, lets say you are using AWS Cognito for authentication, you can keep these dependencies separate from dependencies that access business function, like `/user/{userid}/orders` accesses the Orders table alone.  \n__How is this accomplished?__  \n1. We first export the shared resources from the parent resource `/user`.  \n\n```yaml\n#export from ./api/src/user/serverless.yml\nresources:\n  Outputs:\n    ApiRootUser:\n      Value:\n        Ref: ApiGatewayResourceUser\n      Export:\n        Name: ${self:custom.${self:provider.stage}.Stack}-ApiRootUser-${self:provider.stage}\n    ApiRootUserUseridVar:\n      Value:\n        Ref: ApiGatewayResourceUserUseridVar\n      Export:\n        Name: ${self:custom.${self:provider.stage}.Stack}-ApiRootUserUseridVar-${self:provider.stage}\n```\n2. We then import this shared resources as a `restApiResources` in the child resource `/user/{userid}/orders`  \n```yaml\n#import from ./api/src/user/order/serverless.yml\nprovider:\n  ...\n  apiGateway:\n    restApiId:\n      'Fn::ImportValue': ${self:custom.${self:provider.stage}.Stack}-restApiId-${self:provider.stage}\n    restApiResources:\n      /user/{userid}:\n        'Fn::ImportValue': ${self:custom.${self:provider.stage}.Stack}-ApiRootUserUseridVar-${self:provider.stage}\n```\n\n### Commands\n---\n#### `make buildAll`\nFirst it will run `yarn install` in the `./backend` directory, then it will look at each directory in the `./backend/src` directory and run `yarn install` for each, then it will run `make buildAll` from the `./api` directory.  This will look at each directory in the `./api/src` directory and run `yarn install` for each.\n#### `make deployAll --STAGE='dev'`\nFirst it will run `serverless deploy --stage dev` in the `./backend` directory and then it will run `make deployAll --STAGE='dev'` from the `./api` directory.  This will look at each directory in the `./api/src` directory and run `serverless deploy --stage dev` for each.\n\n### Other commands:\n---\n#### `./api/make endpoint --SERVICE='billing'`\nThis will make a new endpoint in the `./api/src/billing` directory.  It will preload it with the serverless packages for the basic framework as well as set a baseline serverless.yml template.\n#### `make removeAll --STAGE='dev'`\nFirst it will run `serverless remove --stage dev` in the `./backend` directory and then it will run `make removeAll --STAGE='dev'` from the `./api` directory.  This will look at each directory in the `./api/src` directory and run `serverless remove --stage dev` for each.\n#### `make cleanAll`\nFirst it will remove `.serverless/` and `node_modules/**` in the `./backend` directory and then it will run `make removeAll --STAGE='dev'` from the `./api` directory.  This will look at each directory in the `./api/src` directory and remove `.serverless/` and `node_modules/**` for each.\n\n#### `./backend/make deploy STAGE='dev'`\nThis will run `serverless deploy --stage dev` for the `./src/_root` endpoint.  \n#### `./backend/make build SERVICE='orders'`\nThis will run `yarn install` for the backend code.  If you run this command without a `SERVICE` variable it will build the `serverless.yml` dependencies.\n#### `./backend/make remove `\nThis will remove the serverless project, deleting the backend infrastructure.\n#### `./backend/make clean SERVICE='orders'`\nThis will remove the `.serverless` and `node_modules/**` directory for the backend.  If you run this command without a `SERVICE` variable it will clean the `serverless.yml` dependencies.\n\n#### `./api/make deploy SERVICE='user' STAGE='dev'`\nThis will run `serverless deploy --stage dev` for the `./src/user` endpoint.\n#### `./api/make build SERVICE='user'`\nThis will run `yarn install` for the backend code.\n#### `./api/make remove SERVICE='user'`\nThis will remove the serverless project, deleting the backend infrastructure.\n#### `./api/make clean SERVICE='orders'`\nThis will remove the `.serverless` and `node_modules/**` directory for the backend.\n\n## What do do from here:\n* In more complicated examples you would be able to use AWS Cognito in the `/user` endpoint to set up authentication.  This endpoint would be scoped for user functions around Cognito and will likely have similar imports.  \n* You could also import Stripe in a `/billing` endpoint to facilitate collection of payment information.  \n* Within the `/orders` endpoint, you can set up your DynamoDB queries for managing your order collection.  \n* You could set up CI/CD simply by adding a CodePipeline resource, and utilizing CodeBuild to pull down this repository, and run the make files.  \n* Use the `serverless-domain-manager` plug-in to enable domain functionality.  Most of this structure is laid out, you just need to provide a valid `ApiHostedZone`, `ApiSite`, and `ApiCert`.  This can be created in the AWS Console for Route53 and ACM and provided here as variables.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrilom%2Fsls-microservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrilom%2Fsls-microservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrilom%2Fsls-microservice/lists"}