Three Letter Abbreviations (TLA) Sample Application - Implemented Serverless

This repository implements the Three Letter Abbreviations (TLA) Sample Application of the Context Mapper project with serverless technology. It can easily be deployed on AWS. The app illustrates basic CRUD operations using the following AWS services:

• Amazon API Gateway now serves the RESTful HTTP API to access the TLA's.
• AWS Lambda is used (one function per endpoint) to process the request events of the API gateway, load the data from a DynamoDB table and return a response event back to the gateway.
• Amazon DynamoDB is used to persist the TLA's.

Used Technology

The app uses the following tools and frameworks:

• Maven to build the app deployable (JAR)
• Spring Boot and Spring Cloud Function to implement the functions.
• The AWS SDK for Java 2.x to connect to the DynamoDB.
• The Serverless Framework to deploy the whole application on AWS.
  • Including the definition of the API endpoints and the DynamoDB table; see the serverless.yml file.
• GitHub Actions as CI/CD tool to automatically deploy the app to AWS.

Build and Deploy the App

Building the app and its JAR file is done with Maven:

./mvnw clean package

The command above creates a JAR file target\tla-sample-serverless-1.2-SNAPSHOT-aws.jar which contains all the functions (lambdas) of the app. Once successfully built, the app is easily deployed with:

serverless deploy

Note: serverless deploy only works if you have already set up the serverless framework locally, including logging in and connecting to your AWS account. See the Serverless Framework documentation for more information on how to do this.

Once serverless deploy was successful, you can fill the DynamoDB table with some sample data by executing our seed_database function. You can do this via the following command:

sls invoke --function seed_database --data 'unused'

Now you can access the TLA's via the apps API: 🎉

Use Cases and Endpoints

The application currently supports the following use cases, for which we provide some sample CURLs. There is also a Postman collection in the docs folder.

Disclaimer: Please note that we haven't implemented any identity and access control measures for this sample application. All endpoints are publicly available; including the writing ones (commands).

Note that you will need to replace {baseUrl} with the URLs you get from sls deploy in all the following examples.

Endpoint	Method	Description
/tlas	GET	Get all TLA groups including their TLAs (accepted TLAs only).
/tlas?status=PROPOSED	GET	Get TLAs in PROPOSED state.
/tlas	POST	Create a new TLA group (see sample payload below). Containing TLAs will be in PROPOSED state.
/tlas/{groupName}	GET	Get all TLAs of a specific group.
/tlas/{groupName}	POST	Create a new TLA within an existing group (see sample payload below). The created TLA will be in PROPOSED state.
/tlas/all/{name}	GET	Search for a TLA over all groups. This query can return multiple TLAs as a single TLA is only unique within one group.
/tlas/{groupName}/{name}/accept	PUT	Accept a proposed TLA (state transition operation: PROPOSED -> ACCEPTED).

Get All TLA Groups

The /tlas (GET) endpoint returns all TLAs of all TLA groups that are in the ACCEPTED state (read on to see how to propose and accept new TLAs). Note that all TLAs are part of a group.

CURL: curl -X GET {baseUrl}/tlas

Sample output:

[
    {
        "name":"common",
        "description":"Common TLA group",
        "tlas":[
            {
                "name":"TLA",
                "meaning":"Three Letter Abbreviation",
                "alternativeMeanings":[
                    "Three Letter Acronym"
                ]
            }
        ]
    },
    {
        "name":"AppArch",
        "description":"Application Architecture",
        "tlas":[
            {
                "name":"ADR",
                "meaning":"Architectural Decision Record",
                "alternativeMeanings":[
                ],
                "link":"https://adr.github.io/"
            }
        ]
    },
    {
        "name":"DDD",
        "description":"Domain-Driven Design",
        "tlas":[
            {
                "name":"ACL",
                "meaning":"Anticorruption Layer",
                "alternativeMeanings":[
                ]
            },
            {
                "name":"CF",
                "meaning":"Conformist",
                "alternativeMeanings":[
                ]
            },
            {
                "name":"OHS",
                "meaning":"Open Host Service",
                "alternativeMeanings":[
                ]
            },
            {
                "name":"PL",
                "meaning":"Published Language",
                "alternativeMeanings":[
                ]
            },
            {
                "name":"SK",
                "meaning":"Shared Kernel",
                "alternativeMeanings":[
                ]
            }
        ]
    }
]

Note that the endpoint returns all TLAs in state ACCEPTED by default. Use the query parameter status with the value PROPOSED to list TLAs in the PROPOSED state (see example below under "Query Proposed TLAs").

Get TLAs of a Specific Group

The endpoint /tlas/{groupName} (GET) returns all TLAs of a specific group.

Sample CURL: curl -X GET {baseUrl}/tlas/DDD

Sample output:

{
    "name": "DDD",
    "description": "Domain-Driven Design",
    "tlas": [
        {
            "name": "ACL",
            "meaning": "Anticorruption Layer",
            "alternativeMeanings": []
        },
        {
            "name": "CF",
            "meaning": "Conformist",
            "alternativeMeanings": []
        },
        {
            "name": "OHS",
            "meaning": "Open Host Service",
            "alternativeMeanings": []
        },
        {
            "name": "PL",
            "meaning": "Published Language",
            "alternativeMeanings": []
        },
        {
            "name": "SK",
            "meaning": "Shared Kernel",
            "alternativeMeanings": []
        }
    ]
}

Search TLA in All Groups

With the endpoint /tlas/all/{name} (GET) you can search for a TLA through all groups. Note that this might return multiple results, as TLAs are only unique within one group.

Sample CURL: curl -X GET {baseUrl}/tlas/all/ACL

Sample output:

[
    {
        "name": "DDD",
        "description": "Domain-Driven Design",
        "tlas": [
            {
                "name": "ACL",
                "meaning": "Anticorruption Layer",
                "alternativeMeanings": []
            }
        ]
    }
]

Create new TLA Group

Via /tlas (POST) you can create a new TLA group.

Sample CURL 1 (without containing TLA):

curl --header "Content-Type: application/json" \
  -X POST \
  -d '{ "name": "FIN", "description": "Finance TLAs", "tlas": [] }' \
  {baseUrl}/tlas

Sample CURL 2 (with containing TLA):

curl --header "Content-Type: application/json" \
  -X POST \
  -d '{ "name": "FIN", "description": "Finance TLAs", "tlas": [ { "name": "ROI", "meaning": "Return on Investment", "alternativeMeanings": [] } ] }' \
  {baseUrl}/tlas

Sample output: (created group is returned)

{
    "name": "FIN",
    "description": "Finance TLAs",
    "tlas": [
        {
            "name": "ROI",
            "meaning": "Return on Investment",
            "alternativeMeanings": []
        }
    ]
}

Note that the new TLA is now in state PROPOSED and not delivered by the endpoints mentioned above. They only return TLAs in state ACCEPTED by default. Use the following endpoint ("Accept a Proposed TLA") to accept a proposed TLA.

Add New TLA to Existing Group

With the endpoint /tlas/{groupName} (POST) you can add a new TLA to an existing group.

Sample CURL:

curl --header "Content-Type: application/json" \
  -X POST \
  -d '{ "name": "ETF", "meaning": "Exchange-Traded Fund", "alternativeMeanings": [] }' \
  {baseUrl}/tlas/FIN

Sample output: (updated group is returned)

{
    "name": "FIN",
    "description": "Finance TLAs",
    "tlas": [
        {
            "name": "ETF",
            "meaning": "Exchange-Traded Fund",
            "alternativeMeanings": []
        },
        {
            "name": "ROI",
            "meaning": "Return on Investment",
            "alternativeMeanings": []
        }
    ]
}

Note that the new TLA is now in state PROPOSED and not delivered by the endpoints mentioned above. They only return TLAs in state ACCEPTED by default. Use the following endpoint ("Accept a Proposed TLA") to accept a proposed TLA.

Query Proposed TLAs

The endpoint /tlas (GET) offers a query parameter to list all TLAs in the PROPOSED state: /tlas?status=PROPOSED

Sample CURL: curl -X GET {baseUrl}/tlas?status=PROPOSED

Sample output:

[
    {
        "name": "FIN",
        "description": "Finance TLAs",
        "tlas": [
            {
                "name": "ETF",
                "meaning": "Exchange-Traded Fund",
                "alternativeMeanings": []
            },
            {
                "name": "ROI",
                "meaning": "Return on Investment",
                "alternativeMeanings": []
            }
        ]
    }
]

Accept a Proposed TLA

With the endpoint /tlas/{groupName}/{name}/accept (PUT) you can accept a TLA ("name") within a group ("groupName"). This is a so-called state transition operation.

Sample CURL: curl -X PUT {baseUrl}/tlas/FIN/ROI/accept (puts the TLA 'ROI' in group 'FIN' into state ACCEPTED)

This endpoint does not expect a body (JSON) and does also not return one. The command is successful if HTTP state 200 is returned.

Once the TLA is accepted, the query endpoints listed above (such as /tlas or /tlas/{groupName}) will now list them.

Contributing

Contributions are always welcome! Here are some ways how you can contribute:

• Create GitHub issues if you find bugs or just want to give suggestions for improvements.
• This is an open source project: if you want to code, create pull requests from forks of this repository. Please refer to a GitHub issue if you contribute this way.

Licence

This project is released under the Apache License, Version 2.0.