{"id":13701193,"url":"https://github.com/aws-samples/aws-sam-java-rest","last_synced_at":"2025-05-04T20:32:34.726Z","repository":{"id":48555687,"uuid":"145159816","full_name":"aws-samples/aws-sam-java-rest","owner":"aws-samples","description":"A sample REST application built on SAM and DynamoDB that demonstrates testing with DynamoDB Local.","archived":false,"fork":false,"pushed_at":"2024-04-16T05:32:32.000Z","size":46,"stargazers_count":431,"open_issues_count":16,"forks_count":149,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-11-13T07:35:33.420Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2018-08-17T19:39:39.000Z","updated_at":"2024-11-11T00:23:54.000Z","dependencies_parsed_at":"2024-11-13T07:41:30.758Z","dependency_job_id":null,"html_url":"https://github.com/aws-samples/aws-sam-java-rest","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/aws-samples%2Faws-sam-java-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-sam-java-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-sam-java-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-sam-java-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-samples","download_url":"https://codeload.github.com/aws-samples/aws-sam-java-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252395552,"owners_count":21741055,"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":[],"created_at":"2024-08-02T20:01:21.669Z","updated_at":"2025-05-04T20:32:29.713Z","avatar_url":"https://github.com/aws-samples.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# SAM DynamoDB Application for Managing Orders\n\nThis is a sample application to demonstrate how to build an application on DynamoDB using the\nDynamoDBMapper ORM framework to map Order items in a DynamoDB table to a RESTful API for order\nmanagement.\n\n```bash\n.\n├── README.md                               \u003c-- This instructions file\n├── LICENSE.txt                             \u003c-- Apache Software License 2.0\n├── NOTICE.txt                              \u003c-- Copyright notices\n├── pom.xml                                 \u003c-- Java dependencies, Docker integration test orchestration\n├── src\n│   ├── main\n│   │   └── java\n│   │       ├── com.amazonaws.config              \u003c-- Classes to manage Dagger 2 dependency injection\n│   │       │   ├── OrderComponent.java           \u003c-- Contains inject methods for handler entrypoints\n│   │       │   └── OrderModule.java              \u003c-- Provides dependencies like the DynamoDB client for injection\n│   │       ├── com.amazonaws.dao                 \u003c-- Package for DAO objects\n│   │       │   └── OrderDao.java                 \u003c-- DAO Wrapper around the DynamoDBTableMapper for Orders\n│   │       ├── com.amazonaws.exception           \u003c-- Source code for custom exceptions\n│   │       ├── com.amazonaws.handler             \u003c-- Source code for lambda functions\n│   │       │   ├── CreateOrderHandler.java       \u003c-- Lambda function code for creating orders\n│   │       │   ├── CreateOrdersTableHandler.java \u003c-- Lambda function code for creating the orders table\n│   │       │   ├── DeleteOrderHandler.java       \u003c-- Lambda function code for deleting orders\n│   │       │   ├── GetOrderHandler.java          \u003c-- Lambda function code for getting one order\n│   │       │   ├── GetOrdersHandler.java         \u003c-- Lambda function code for getting a page of orders\n│   │       │   └── UpdateOrderHandler.java       \u003c-- Lambda function code for updating an order\n│   │       └── com.amazonaws.model               \u003c-- Source code for model classes\n│   │           ├── request                       \u003c-- Source code for request model classes\n│   │           │   ├── CreateOrderRequest.java      \u003c-- POJO shape for creating an order\n│   │           │   ├── GetOrDeleteOrderRequest.java \u003c-- POJO shape for getting or deleting an order\n│   │           │   ├── GetOrdersRequest.java        \u003c-- POJO shape for getting a page of orders\n│   │           │   └── UpdateOrderRequest.java      \u003c-- POJO shape for updating an order\n│   │           ├── response                      \u003c-- Source code for response model classes\n│   │           │   ├── GatewayResponse.java         \u003c-- Generic POJO shape for the APIGateway integration\n│   │           │   └── GetOrdersResponse.java       \u003c-- POJO shape for a page of orders\n│   │           └── Order.java                    \u003c-- POJO for Order resources\n│   └── test                                      \u003c-- Unit and integration tests\n│       └── java\n│           ├── com.amazonaws.config              \u003c-- Classes to manage Dagger 2 dependency injection\n│           ├── com.amazonaws.dao                 \u003c-- Tests for OrderDao\n│           ├── com.amazonaws.handler             \u003c-- Unit and integration tests for handlers\n│           │   ├── CreateOrderHandlerIT.java     \u003c-- Integration tests for creating orders\n│           │   ├── CreateOrderHandlerTest.java   \u003c-- Unit tests for creating orders\n│           │   ├── DeleteOrderHandlerTest.java   \u003c-- Unit tests for deleting orders\n│           │   ├── GetOrderHandlerTest.java      \u003c-- Unit tests for getting one order\n│           │   ├── GetOrdersHandlerTest.java     \u003c-- Unit tests for getting a page of orders\n│           │   └── UpdateOrderHandlerTest.java   \u003c-- Unit tests for updating an order\n│           └── com.amazonaws.services.lambda.runtime \u003c-- Unit and integration tests for handlers\n│               └── TestContext.java              \u003c-- Context implementation for use in tests\n└── template.yaml                                 \u003c-- Contains SAM API Gateway + Lambda definitions\n```\n\n## Requirements\n\n* [AWS CLI](https://aws.amazon.com/cli/) already configured with at least PowerUser permission\n* [Java SE Development Kit 8 installed](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)\n* [Docker installed](https://www.docker.com/community-edition)\n* [Maven](https://maven.apache.org/install.html)\n* [SAM CLI](https://github.com/awslabs/aws-sam-cli)\n* [Python 3](https://docs.python.org/3/)\n\n## Setup process\n\n### Installing dependencies\n\nWe use `maven` to install our dependencies and package our application into a JAR file:\n\n```bash\nmvn package\n```\n\n### Local development\n\n**Invoking function locally through local API Gateway**\n1. Start DynamoDB Local in a Docker container. `docker run -p 8000:8000 amazon/dynamodb-local`\n2. Create the DynamoDB table. `aws dynamodb create-table --table-name orders_table --attribute-definitions AttributeName=orderId,AttributeType=S --key-schema AttributeName=orderId,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://localhost:8000`\n3. Start the SAM local API.\n - On a Mac: `sam local start-api --env-vars src/test/resources/test_environment_mac.json`\n - On Windows: `sam local start-api --env-vars src/test/resources/test_environment_windows.json`\n - On Linux: `sam local start-api --env-vars src/test/resources/test_environment_linux.json`\n\nIf the previous command ran successfully you should now be able to hit the following local endpoint to\ninvoke the functions rooted at `http://localhost:3000/orders`\n\n**SAM CLI** is used to emulate both Lambda and API Gateway locally and uses our `template.yaml` to\nunderstand how to bootstrap this environment (runtime, where the source code is, etc.) - The\nfollowing excerpt is what the CLI will read in order to initialize an API and its routes:\n\n```yaml\n...\nEvents:\n    GetOrders:\n        Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api\n        Properties:\n            Path: /orders\n            Method: get\n```\n\n## Packaging and deployment\n\nAWS Lambda Java runtime accepts either a zip file or a standalone JAR file - We use the latter in\nthis example. SAM will use `CodeUri` property to know where to look up for both application and\ndependencies:\n\n```yaml\n...\n    GetOrdersFunction:\n        Type: AWS::Serverless::Function\n        Properties:\n            CodeUri: target/aws-sam-java-rest-1.0.0.jar\n            Handler: com.amazonaws.handler.GetOrdersHandler::handleRequest\n```\n\nFirstly, we need a `S3 bucket` where we can upload our Lambda functions packaged as ZIP before we\ndeploy anything - If you don't have a S3 bucket to store code artifacts then this is a good time to\ncreate one:\n\n```bash\nexport BUCKET_NAME=my_cool_new_bucket\naws s3 mb s3://$BUCKET_NAME\n```\n\nNext, run the following command to package our Lambda function to S3:\n\n```bash\nsam package \\\n    --template-file template.yaml \\\n    --output-template-file packaged.yaml \\\n    --s3-bucket $BUCKET_NAME\n```\n\nNext, the following command will create a Cloudformation Stack and deploy your SAM resources.\n\n```bash\nsam deploy \\\n    --template-file packaged.yaml \\\n    --stack-name sam-orderHandler \\\n    --capabilities CAPABILITY_IAM\n```\n\n\u003e **See [Serverless Application Model (SAM) HOWTO Guide](https://github.com/awslabs/serverless-application-model/blob/master/HOWTO.md) for more details in how to get started.**\n\nAfter deployment is complete you can run the following command to retrieve the API Gateway Endpoint URL:\n\n```bash\naws cloudformation describe-stacks \\\n    --stack-name sam-orderHandler \\\n    --query 'Stacks[].Outputs'\n```\n\n## Testing\n\n### Running unit tests\nWe use `JUnit` for testing our code.\nUnit tests in this sample package mock out the DynamoDBTableMapper class for Order objects.\nUnit tests do not require connectivity to a DynamoDB endpoint. You can run unit tests with the\nfollowing command:\n\n```bash\nmvn test\n```\n\n### Running integration tests\nIntegration tests in this sample package do not mock out the DynamoDBTableMapper and use a real\nAmazonDynamoDB client instance. Integration tests require connectivity to a DynamoDB endpoint, and\nas such the POM starts DynamoDB Local from the Dockerhub repository for integration tests.\n\n```bash\nmvn verify\n```\n\n### Running end to end tests through the SAM CLI Local endpoint\nRunning the following end-to-end tests requires Python 3 and the `requests` pip\npackage to be installed. For these tests to succeed,\n```bash\npip3 install requests\npython3 src/test/resources/api_tests.py 3\n```\n\nThe number that follows the test script name is the number of orders to create in the\ntest. For these tests to work, you must follow the steps for [local development](#local-development).  \n\n# Appendix\n\n## AWS CLI commands\n\nAWS CLI commands to package, deploy and describe outputs defined within the cloudformation stack:\n\n```bash\nsam package \\\n    --template-file template.yaml \\\n    --output-template-file packaged.yaml \\\n    --s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME\n\nsam deploy \\\n    --template-file packaged.yaml \\\n    --stack-name sam-orderHandler \\\n    --capabilities CAPABILITY_IAM \\\n    --parameter-overrides MyParameterSample=MySampleValue\n\naws cloudformation describe-stacks \\\n    --stack-name sam-orderHandler --query 'Stacks[].Outputs'\n```\n\n## Bringing to the next level\n\nNext, you can use the following resources to know more about beyond hello world samples and how others\nstructure their Serverless applications:\n\n* [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Faws-sam-java-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-samples%2Faws-sam-java-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Faws-sam-java-rest/lists"}