RestfulQR

QR Codes delivered by REST

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

About The Project

RestfulQR is a simple REST API to create and serve QR codes as part of a microservices architecture. The project uses the QRCoder library to create QR codes. The project aims to serve all functionality available in QRCoder via REST calls.

Built With

• QRCoder
• .NET 5.0
• ASP.NET Core
• Postgres
• Seq
• Docker (docker-compose)

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

You will need Docker installed in order to run the project via docker-compose.

• Docker installed in order to run the project via docker-compose.
• Atleast .NET 5.0 installed to debug and run via dotnet
• Optional: Visual Studo 2019

AWS

RestfulQr uses S3 to persist images. You will need to create a S3 bucket to use. Once you create the bucket, you need to configure the appSettings.json file with your values.

For example,

  "AWS": {
    "Profile": "your-profile",
    "Region": "your-region",
    "ProfilesLocation": "your-aws-credentials"
  },
  "S3": {
    "BucketName": "your-bucket-name"
  }

You will also need to set bind your docker containers with the right volume for your credentials in docker-compose.override.yml

Installation

1. Clone the repo

   git clone https://github.com/coffeexcode/RestfulQr.git

2. Start via docker-compose

   docker-compose up

Usage

This project is meant to be incredibly simple to use if you are familiar with REST. For testing and development, the recommended tool is Postman.

Note: These steps assume that you are running locally with the default URL settings. This implies the application is running at http://localhost:14000

You can generate a retrieve your first QR code using the following steps:

1. Ensure the project is running via docker-compose

   docker-compose up

2. Get an API key.

   Note: If you are running in development, you can skip this step and replace the api key with 'development' for future steps.

   curl --location --request POST 'https://localhost:14000/api/v1/apikey'

3. Use the API key to generate a simple QR code from JSON data with default settings.

   curl --location --request POST 'https://localhost:14000/api/v1/qrcode/json' \
   --header 'X-Api-Key: YOUR-API-KEY-GOES-HERE' \
   --header 'Content-Type: application/json' \
   --data-raw '{
   "demo": "test"
   }'

   If the request was successfully, you should get a 201 CREATED response with a body like the following:

   {
       "succeeded": true,
       "errors": null,
       "createdQrCode": {
           "filename": "3bc3d64e-05b8-4af5-a106-dcaff7815bd3.png",
           "created": "2020-12-03T12:53:09.1174748+00:00",
           "createdBy": "YOUR-API-KEY-GOES-HERE"
       },
       "data": {
           "demo": "test"
       }
   }

4. Retrieve your QR code! Pass the filename from step #3 into the URL of the following

   curl --location --request GET 'https://localhost:14000/images/3bc3d64e-05b8-4af5-a106-dcaff7815bd3.png' \
   --header 'X-Api-Key: development'

Help

RestfulQR has swagger built in. While running in development, you can browse to http://localhost:14000/swagger/index.html to view the swagger definintion and examples of using all of the endpoints available.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are always welcome. Contributions should be in-line with the project goals: i.e. single use scenarios or specific businesses casesly will likely be denied. Any contributions you make are greatly appreciated. In general, you can contribute by doing the following:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Nathan Brown - @kilosandcoffee

Project Link: https://github.com/coffeexcode/RestfulQr

Acknowledgements

• QRCoder. This project would not have been successfully without this awesome library.