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:

• Developers who want to quickly and efficiently develop an API without microservices architecture (for now) concentrating only on the business.
• Developers and students who want to learn to work with the vert.x framework.
• Developers who need to develop an API with vert.x and have little or no knowledge of vert.x

It has the following functionalities:

• HTTP BASIC AUTHENTICATION
• Access to configuration file
• Enabling and disabling endpoints
• Endpoints with GET, POST, PUT y DELETE
• Cross-Origin Resource Sharing (CORS) support
• Execution of blocking code and non-blocking code
• Asynchronous HTTP responses
• System logs
• Builtin SwaggerUI documentation
• Administration endpoints
• Handling HTTP query parameters
• Handling of POST body parameters
• Handling of Multipart files
• Scheduling periodic tasks
• Unit tests for each endpoint
• Postman Collection for testing purposes
• Fatjar generation
• Simple jar generation
• Execution of ant tasks to generate a directory with everything necessary for the deployment

Documentation

Prerequisites 📋

• Apache Maven
• JDK 8+
• Postman (optional)

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:

• a pom.xml file

• a main verticle file (src/main/java/com.bugsyteam.verticles/MainVerticle.java)

• a traditional main class (src/main/java/com.bugsyteam.main/VertxApplication.java)

• unit test cases (src/main/test/com.bugsyteam.verticles/MainVerticleTest.java)

• collection of utility classes (src/main/java/com.bugsyteam.utils)

• collection of endpoint call handlers (src/main/java/com.bugsyteam.endpoints)

• a Swagger specification to document the API (postmanTests/ssv-api.postman_collection.json)

• a Postman collection to test the API (src/main/resources/webroot/node_modules/swagger-ui-dist/ssv_api_specification.yml)

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

• package - Compile to /target directory
• clean - clears all content from /target before compiling
• install - generate the deployment directory ../PROJECT_NAME-export

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
}

• http.port - port on which the service will listen.

• api.username y api.password - username and password to access the different endpoints using HTTP BASIC AUTHENTICATION.

• cors.enable - Enable CORS support.

• endpoint.admin.enable - Enable management endpoints.

• endpoint.swagger.enable - Enable SwaggerUI documentation in /doc/ path.

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 🛠️

• Vert.x - Framework for building reactive applications on the JVM
• Maven - Build automation
• Postman - API Testing
• Eclipse - Development IDE

Authors ✒️

• Jonad García San Martín - Development and Documentation - jgarciasm89

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.

---