Home

Awesome

ssv-api (Starter Single Verticle API)

Template REST API project ready to deploy. REST API based in vert.x framework with lots of plumbing code, examples, use cases and documentation to quickly develope an API with almost no knowledge of vert.x and without any waste of time.

It is intended to:

It has the following functionalities:

Documentation

Prerequisites 📋

Getting started 🚀

Since you will likely want to use (Git) version control as well, the fastest route is create a new repository from ssv-api template. This will create a new Github repository using the same structure that ssv-api but with the personalized information that you has to provide. To do this you has to press Use this template green button placed at the right top corner of <> Code section of this repository.

Or do it by hand by clone the repository, delete its .git/ folder and then create a new Git repository:

git clone https://github.com/jgarciasm/ssv-api.git PROJECT_NAME
cd PROJECT_NAME
rm -rf .git
git init

Replace PROJECT_NAME with the name of your project.

Open the pom.xml file and customize the groupId, artifactId, version, output.dir, and jar.name. You can also change the main.verticle property to use your own package name and verticle class.

See ** Deployment ** to know how to deploy the project.

Structure of the project 🏬

The project contains:

All the classes and methods are well documented for study purposes.

Compile 📦

Maven is used to compile. For those who are not familiar, it can be compiled using any of the following commands:

mvn package
mvn clean package
mvn clean package install

Configuration and Deployment ⚙️

The file conf/conf.json must be modified with the desired parameters.

{
"http.port" : 8080,
"api.username" : "user",
"api.password" : "passw",
"cors.enable" : true,
"endpoint.admin.enable" : true,
"endpoint.swagger.enable" : true
}

There are at least 3 ways to run the service:

Variant 1 (Development environment):

Run it as an Eclipse project. For this we run the Main com.bugsyteam.main.VertxApplication.java as a Java Application. It is not recommended to debug the project since due to the asynchronous nature of Vert.x and certain restrictions of this framework it will give execution errors.

Variant 2 (Development environment):

Run it with:

mvn package exec:java

This command compiles the project, generates a fat-jar in /target directory, runs the tests and executes the service.

Variant 3:

This should be the variant used to deploy the service on a server in test or production environment. First compile with:

mvn clean package install

This will create a directory PROJECT_NAME-export at the same height as the project directory. Inside this directory there is a file PROJECT_NAME-VERSION.jar that is the one that we will display, along with other directories and files necessary for the execution. Then navigate to the new directory.

VERSION will be replaced with the version property of your pom.xml.

cd ../PROJECT_NAME-export

Open the conf/config.json file and edit it with the necessary configurations (if not previously done). Copy the directory to the final location and deploy with:

java -jar PROJECT_NAME-VERSION.jar

Once running, the service can be tested by opening http://localhost:8080/test in the browser. It should respond HTTP 200

Testing 🔎

In the directory of the project there is a "postmanTests" folder that has a Postman collection that has a battery of tests for the API endpoints. With this project, from Postman, code examples can be self-generated to consume the different services for different languages and technologies.

It also has a battery of unit tests that are run every time the project is compiled. This behavior can be disabled by setting the skipTests property of the pom.xml to true. It is highly recommended to leave it in false since if any change in the code adds an error to the system, it will be detected quickly.

Build with 🛠️

Authors ✒️

License 📄

jgarciasm/ssv-api is licensed under the Apache License 2.0. A permissive license whose main conditions require preservation of copyright and license notices. Contributors provide an express grant of patent rights. Licensed works, modifications, and larger works may be distributed under different terms and without source code.