Date:	Author:	Version:	Changes:	Completed	Ext.	Is in Core	Jira Ref.
05 April 2016	tpl	0.1	Doc. created	No	x	N/A
14 April 2016	Anders GranauHøfft	0.2	Sections expanded	No	x	N/A	CDRRM-733
11 May 2016	Emil Ifrim	0.3	Database configuration	No	x	N/A
20 March 2017	Emil Ifrim	0.4	Redesign Update	No	x	N/A
01 April 2018	Emil Ifrim	0.5	Redesign Update	No	x	N/A
15 January 2019	SD	0.6	Download pdf-file

Overview

The customer project can deploy REST as two services (REST Auth and REST Core) or as three services (REST Auth, REST Core and REST Cust).

Two-service deployment: the custom endpoints (usualy developed in it's own standalone customer library project) are packaged together with the core endpoints

pros: only two services to maintain, documentation can be browsed at the same address for both core and custom endpoints
cons: in a intensive production setup, where high availability is a must, taking down the endpoints will happen for both(core and custom); also, in case of scalability, this has to be the same for both

Three-service deployment: the custom endpoints (usualy developed in it's own standalone customer library project) are packaged and deployed separately (REST Core has it's own war file, same for REST Cust)

pros: more scalable and maintainable (e.g if custom endpoints Tomcat needs maintainance, it can be stopped without affecting REST Core service)
cons: one more service to main and deploy.

Below it's an example with three modules, Baseline project can be used as an example for a two-rest-service deployment

This is a brief guide on how to install the REST service (rator-rest-api project and rator-rest-api-auth project). A customer rest project involves deploying three artifacts:

authentication project (war) - this is called in order to obtain an authentication token.
core REST services (war) - this contains core REST services, but in a customer project context(customer project dependencies).
customer REST services (war) - this contains customer REST services with customer project dependencies.

The reason behind this structure is to allow versioning of the projects.

The document also describes how to deploy the third-party documentation service called Swagger UI. This is not required for the REST service to work, but provides useful documentation.

How to Include the REST API in Customer Projects

This section is about how to modify the customer project's pom so as to include the rator-rest-api in the build.

Note

The name of the projects in the examples can be changed according to the customer setup. The examples are presented mainly for the structure of the projects.

You will need to create a new pom and put it in a subfolder of your customer project. Follow these steps:

Create a customer REST API module, i.e. a "wrapper pom" that contain 3 other modules:
1. core REST module.
2. customer REST module
3. auth module

Example project structure:

Customer REST-Webapps pom Example

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.cdrator.projects.customer_project</groupId>
    <artifactId>customer_project</artifactId>
    <version>3.0-SNAPSHOT</version>
    <relativePath>../../pom.xml</relativePath>
  </parent>
  <artifactId>customer_project-rest-parent</artifactId>
  <packaging>pom</packaging>
  <name>customer_project REST modules</name>
  <description>customer_project REST modules</description>
  
  <properties>
		<failOnMissingWebXml>false</failOnMissingWebXml>
  </properties>
  
  <modules>
    <module>core-rest-app</module>
    <module>customer-rest-app</module>
    <module>rest-api-auth-app</module>
  </modules>
  <dependencyManagement>
	<dependencies>
		<dependency>
			<!-- Jboss logging that is used by hibernate-validator has a conflict with the one used by jdiameter -->
			<groupId>${project.groupId}</groupId>
			<artifactId>customer_project-billing</artifactId>
			<version>${project.version}</version>
			<scope>runtime</scope>
			<exclusions>
				<exclusion>
					<groupId>javax.ws.rs</groupId>
					<artifactId>jsr311-api</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.jboss.logging</groupId>
					<artifactId>jboss-logging</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.jboss.logging</groupId>
					<artifactId>jboss-logging-spi</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
				<groupId>com.cdrator.core</groupId>
				<artifactId>rator-billing</artifactId>
				<scope>runtime</scope>
				<version>${com.cdrator.core.version}</version>
				<exclusions>
					<exclusion>
						<artifactId>servlet-api</artifactId>
						<groupId>javax.servlet</groupId>
					</exclusion>
					<exclusion>
						<groupId>org.apache.bval</groupId>
						<artifactId>bval-jsr303</artifactId>
					</exclusion>
					<exclusion>
						<groupId>org.ow2.asm</groupId>
						<artifactId>asm-all</artifactId>
					</exclusion>
				</exclusions>
			</dependency>
			<dependency>
				<groupId>com.google.guava</groupId>
				<artifactId>guava</artifactId>
				<version>18.0</version>
			</dependency>
	</dependencies>
</dependencyManagement>	
  <build>
    <sourceDirectory>src/main/java</sourceDirectory>
    <plugins>
	   <plugin>
			<groupId>com.ning.maven.plugins</groupId>
			<artifactId>maven-duplicate-finder-plugin</artifactId>
			<configuration>
				<ignoredResources combine.children="append">
					<ignoredResource>META-INF/validation-configuration-1.0.xsd</ignoredResource>
					<ignoredResource>META-INF/validation-mapping-1.0.xsd</ignoredResource>
					<ignoredResource>META-INF/additional-spring-configuration-metadata.json</ignoredResource>
					<ignoredResource>META-INF/spring-configuration-metadata.json</ignoredResource>
					<ignoredResource>META-INF/spring.factories</ignoredResource>
					<ignoredResource>META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat</ignoredResource>
				</ignoredResources>
			</configuration>
		</plugin>
	</plugins>
			
  </build>
</project>

2. Optional: Add a build section to the newly created pom wherein an alternative output directory is specified for the war + an alternative name.

3. Add a reference to the created module in a module tag in the projects main pom. Fx: <module>modules/rest-webapps</module>

4. Create a module/subproject for the customer REST services (customized services) under src folder. This project will hold the REST services without any web descriptor. This project will be added as a depedency to the customer-rest-api wrapper module(point 1.b)

Example project structure:

Note

The pom files below are presented just as examples and should be used accordingly.

Core REST-API pom Example

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>com.cdrator.projects.customer_project</groupId>
		<artifactId>customer_project-rest-parent</artifactId>
		<version>3.0-SNAPSHOT</version>
		<relativePath>../pom.xml</relativePath>
	</parent>

	<artifactId>customer_project-rest-api-core</artifactId>
	<packaging>war</packaging>
	<name>customer_project REST API (Core Services)</name>
	<description>customer_project REST API (Core Services)</description>

	<dependencies>
		<dependency>
			<groupId>${project.groupId}</groupId>
			<artifactId>customer_project-billing</artifactId>
			<version>${project.version}</version>
			<scope>runtime</scope>
			<exclusions>
				<exclusion>
					<groupId>javax.ws.rs</groupId>
					<artifactId>jsr311-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
 
		<dependency>
			<groupId>com.cdrator.core</groupId>
			<artifactId>rator-billing</artifactId>
			<scope>runtime</scope>
			<exclusions>
				<exclusion>
					<artifactId>servlet-api</artifactId>
					<groupId>javax.servlet</groupId>
				</exclusion>
				<exclusion>
					<groupId>org.apache.bval</groupId>
					<artifactId>bval-jsr303</artifactId>
				</exclusion>
			</exclusions>
		</dependency>

		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-config</artifactId>
		</dependency>
		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-resources</artifactId>
		</dependency>
		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-bootstrap</artifactId>
			<classifier>webapp</classifier>
			<type>war</type>
		</dependency>
		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-bootstrap</artifactId>
		</dependency>
	</dependencies>

	<build>
		<finalName>customer_project-rest-api-core</finalName>

		<plugins>
			<plugin>
				<artifactId>maven-war-plugin</artifactId>
				<configuration>
					<outputDirectory>${basedir}/../../../target</outputDirectory>
					<excludes>log4j.properties</excludes>
					<!-- Exclude JCL and LOG4J since all logging should go through SLF4J. 
						Note that we're excluding log4j-<version>.jar but keeping log4j-over-slf4j-<version>.jar -->
					<packagingExcludes>
						WEB-INF/log4j.properties,
						WEB-INF/lib/javax.el-api-2.2.4.jar
					</packagingExcludes>
				</configuration>
			</plugin>
			<plugin>
				<groupId>com.cdrator.maven.plugins</groupId>
				<artifactId>rator-maven-renamer-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

Customer REST-API pom Example

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.cdrator.projects.customer_project</groupId>
    <artifactId>customer_project-rest-parent</artifactId>
    <version>3.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  
  <artifactId>customer_project-rest-api-cust</artifactId>
  <packaging>war</packaging>
  <name>customer_project REST API (Customized Services)</name>
  <description>customer_project REST API (Customized Services)</description>
  
  <dependencies>
  		<dependency>
			<groupId>${project.groupId}</groupId>
			<artifactId>customer_project-billing</artifactId>
			<version>${project.version}</version>
			<scope>runtime</scope>
			<exclusions>
				<exclusion>
					<groupId>javax.ws.rs</groupId>
					<artifactId>jsr311-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>${project.groupId}</groupId>
			<artifactId>customer_project-rest-api</artifactId>
			<version>${project.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-config</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-bootstrap</artifactId>
			<classifier>webapp</classifier>
			<type>war</type>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>com.cdrator</groupId>
			<artifactId>rator-rest-api-bootstrap</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>javax.ws.rs</groupId>
			<artifactId>javax.ws.rs-api</artifactId>
		</dependency>
		<dependency>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-annotations</artifactId>
		</dependency>
  </dependencies>
    
  <build>
		<finalName>customer_project-rest-api-cust</finalName>
		
		<plugins>
			<plugin>
				<artifactId>maven-war-plugin</artifactId>
				<configuration>
					<outputDirectory>${basedir}/../../../target</outputDirectory>
					<excludes>log4j.properties</excludes>
					<!-- Exclude JCL and LOG4J since all logging should go through SLF4J. 
						Note that we're excluding log4j-<version>.jar but keeping log4j-over-slf4j-<version>.jar -->
					<packagingExcludes>
						WEB-INF/log4j.properties,
						WEB-INF/lib/javax.el-api-2.2.4.jar
					</packagingExcludes>
				</configuration>
			</plugin>
			<plugin>
				<groupId>com.cdrator.maven.plugins</groupId>
				<artifactId>rator-maven-renamer-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

Auth REST-API pom Example

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>com.cdrator.projects.customer_project</groupId>
		<artifactId>customer_project-rest-parent</artifactId>
		<version>3.0-SNAPSHOT</version>
		<relativePath>../pom.xml</relativePath>
	</parent>
	<artifactId>customer_project-rest-api-auth</artifactId>
	<packaging>war</packaging>
	<name>customer_project REST API Auth</name>
	<description>customer_project REST API Auth</description>

	<dependencies>
		 <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>customer_project-billing</artifactId> <!-- or rator-billing if there is no customization in the billing layer of the customer project-->
            <version>${project.version}</version>
            <scope>runtime</scope>
 			<exclusions>
            	<exclusion>
					<groupId>org.apache.bval</groupId>
					<artifactId>bval-jsr303</artifactId>
				</exclusion>
            </exclusions>
        </dependency>
		<dependency>
			<groupId>com.cdrator.rest</groupId>
			<artifactId>rator-rest-api-auth</artifactId>
			<classifier>webapp</classifier>
			<type>war</type>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>com.cdrator.rest</groupId>
			<artifactId>rator-rest-api-auth</artifactId>
			<scope>runtime</scope>
		</dependency>
	</dependencies>

	<build>
		<finalName>customer_project-rest-api-auth</finalName>
		<plugins>
			<plugin>
				<artifactId>maven-war-plugin</artifactId>
				<configuration>
					<outputDirectory>${basedir}/../../../target</outputDirectory>
					<excludes>log4j.properties</excludes>
					<!-- Exclude JCL and LOG4J since all logging should go through SLF4J. 
						Note that we're excluding log4j-<version>.jar but keeping log4j-over-slf4j-<version>.jar -->
					<packagingExcludes>
						WEB-INF/log4j.properties,
						WEB-INF/lib/javax.el-api-2.2.4.jar
					</packagingExcludes>
				</configuration>
			</plugin>
			<plugin>
				<groupId>com.cdrator.maven.plugins</groupId>
				<artifactId>rator-maven-renamer-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

Java 21

Since REST 17.0 (core 11.23), correspinding to Java 21 upgrade, the rator-rest-api-auth artifact has been replaced with rator-authorization-server.

Install Tomcat 9

A Tomcat must be installed on your environment.

Since REST 17.0 (core 11.23), correspinding to Java 21 upgrade, Tomcat 10 or above is needed.

Installation

If you are developing from Eclipse, and deploying to a local Tomcat installation, Eclipse automatically handles build and deployment. See fx the Tomcat-section of this guide.

This section describes installation of the core services. For a customer setup, an additional war has to be deployed (the one containing the customized REST services)

Retrieve the rator-rest-api .war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build).
Retrieve the rator-rest-api-auth.war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build).
Copy the war files to the Tomcat webapps directory and (re-)start the Tomcat application.
Retrieve the swagger-ui dist folder (either from Github, or from our own repositories, see Resources. Or by building the project yourself, see Build).
Copy the dist folder to the Tomcat webapps directory and (re-)start the Tomcat application. You probably want to rename the dist folder to swagger-ui.
1. Nb This can be a different Tomcat installation than in step 2, or the same.
In your browser, enter the URL "http://<Swagger server and port>/<base-path>/?url=http://<REST server and port>/<base-path>/api/swagger.json".
You should now see a list of the resources available on the REST server.
In order to access secure resources through swagger-ui, one additional parameter must be configured in the Properties.txt file:
oauth2 selfcare client
```
rest.api.accessTokenUri=http://<host>:<port/<auth-app-context>/oauth/token #example: http://10.45.1.81:8081/rator-rest-api-auth/oauth/token
```

rator-rest-api	Swagger UI
Compatibility matrix
1.0	2.1.1
3.0.1-SNAPSHOT	3.20.0

Database Setup

Run table_changes.sql that can be found in the project (rator-rest-api)

Configure REST api clients - who is allowed to get security tokens in order to access resources that require authentication/authorization. Here are some examples:

oauth2 selfcare client

Insert into OAUTH_CLIENT_DETAILS
   (CLIENT_ID, CLIENT_SECRET, SCOPE, AUTHORIZED_GRANT_TYPES, ACCESS_TOKEN_VALIDITY, REFRESH_TOKEN_VALIDITY, AUTHORITIES)
 Values
   ('rator-selfcare-web-app', 'ratorselfcare', 'read,write', 'password', 600, 0, 'ACCESS_BRAND_brandKey'); --replace brandKey with a valid brand in the setup

Note: Swagger-ui client should only be used in development environments!

oauth2 swagger-ui client

Insert into OAUTH_CLIENT_DETAILS
   (CLIENT_ID, CLIENT_SECRET, SCOPE, AUTHORIZED_GRANT_TYPES, ACCESS_TOKEN_VALIDITY, AUTOAPPROVE, AUTHORITIES)
 Values
   ('your-client-id', 'your-client-secret', 'read-write:api-doc', 'password,operator_password,client_credentials', 
    600, 'true', 'ACCESS_BRAND_brandKey'); --replace brandKey with a valid brand in the setup

Verify Deployment

In your browser, enter the URL:

http://<Swagger server and port>/<base-path>/?url=http://<REST server and port>/<base-path>/api/swagger.json

You should now see a list of the resources available on the REST server.

If both the Swagger UI and the REST application has been deployed to the same Tomcat, and if Tomcat's default "base path to web-app configuration" has not been overwritten, the URL to call may look like this:

http://localhost:8080/swagger-ui/?url=http://localhost:8080/rator-rest-api-bootstrap/api/swagger.json

If you get an error response from the server, try pin pointing the problem:

Verify that the Swagger UI service is available: Enter http://<Swagger server and port>/<base-path> in a browser. <base-path> will by "swagger-ui" if you have followed the installation steps and if the default Tomcat behavior has not been modified. If you get a 404 server error, see step 3.
Verify that the rator-selfcare-rest-api is available: Enter http://<REST server and port>/<base-path>/api. This should show you the index.html page, which is (currently) a (very) short text stating that you have reached the RESTful webservice. If you get a 404 error response from the server, see step 3.
Tomcat maps "base paths" to the web apps in your Tomcats webapps folder. The is called the context. Unless you specify otherwise, the base path is the name of the given web application's main folder. If you get a 404 error response from the server, you should investigate if Tomcat's default base path/context configuration has been overwritten, and with which values. This is general Tomcat configuration, and as such outside the scope of this documentation.

A brief remark on Tomcat's base path:

Your Tomcat installation's server.xml file will sometimes specify a base path for the REST project in a <context.../> tag.

<Context antiJARLocking="true" docBase="C:\Program Files\Tomcat\apache-tomcat-7.0.54\webapps\rator-rest-api-bootstrap" path="" reloadable="true" source="org.eclipse.jst.jee.server:rator-selfcare-rest-api"/>

If the Tomcat's server.xml file had a <Context/> tag like the above, where the base path for the rator-rest-api-botstrap is set to the empty string, the project would be available at http://localhost:8080/api/<SOME RESOURCE>.

When deploying from Eclipse, such entry might have been added automatically. Configuring the context in the server.xml seems to be discouraged by various online sources.

If 404 errors are returned from the server, when accessing the deployed services, you must either modify the base path, or modify the URL accordingly. If you are deploying from Eclipse, you may want to specify the base path on the modules sub-pane of the server pane.

Resources

Source code is available both in our SVN repository, in Jenkins and in Nexus (where our Jenkins build deploys to).

The artifacts to deploy (the REST application and Swagger UI) can either be produced manually from source code (see below - Installation guide), downloaded from Nexus, or retrieved from Jenkins.

SVN/GIT

Please notice that the Swagger UI web service is not a Java project, but a collection of HTML, Javascript and CSS.

Jenkins

Jobs are set up to do continuous integration. The artifacts produced from a build are placed in the given job's "Workspace" (Arbejdsområde) page, in the folder "target":

http://cdrsrvbuild2.cdrator.internal:8080/jenkins/job/rator-rest-api-master/

Nexus

Jenkins jobs are configured to deploy to Nexus. On Nexus, both the source code and the artifacts produced from the build are found.

http://cdrsrvbuild:8081/nexus/index.html

Build

This paragraph contains information about how to "manually" build the referenced projects from terminal (Mostly of interest to developers).

For information about how to include the rator-rest-api project in the customer project's build, see the section 'How to include the REST api in customer projects'.

You can build the artifacts yourself. Notice that the Swagger UI is not a Java project, for which reason its build procedure is different than the REST application.

rator-rest-api

Check out the source code (See the Resources paragraph above)
Create the artifact: mvn clean package
You should now have a rator-rest-api-bootstrap-<version>.war file in the target folder.

rator-rest-api-auth

Check out the source code (See the Resources paragraph above)
Create the artifact: mvn clean package
You should now have a rator-rest-api-auth-<version>.war file in the target folder.

Please notice that the REST project use Java 8 functionality. If your JAVA_HOME environment variable points to a jdk7, or below, you will get compile errors.

Since, in the time of writing, most other CDRator projects are compiled with jdk7, you might have your JAVA_HOME pointing to jdk7. In that case you need to change your JAVA_HOME. This can be done manually by Windows GUIs. In case you only want this change to be temporary, you can use the following convenience script (where you replace the path to jdk8 with your own installation):

@echo off
set prev_java_home=%JAVA_HOME%
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_72
cmd /c mvn %*
set JAVA_HOME=%prev_java_home%

Place the script in a file called, fx, mvn8.bat and place the file in your apache-maven-<version>/bin folder (where an mvn.bat file should already be present). With this in place, the command in step 2 should be: mvn8 clean package

Developers working with the dependent project rator-core-api, should likewise be aware that this is a Java 8 application.

Swagger UI

Refer to http://swagger.io/swagger-ui/, or follow the steps below for building locally (in case the default build from github does not suit the needs).

Prerequisites:

You have node.js installed, and thereby access to the tool npm (node package manager). If not, install node.js from https://nodejs.org/en/download/ (there is a .msi installer for windows). The installer will most likely automatically add the nodejs folder to the system environment so as to avoid needing to write the full path to the node.js executable. Similiarly, Gulp should be installed. See online guides.

In a command prompt assert a successfull install by writing "node -v" so as to output the version number.

Now, follow these steps to build the Swagger UI:

Check out the source code (See the Resources paragraph above.)
npm install
gulp
You should see the distribution under the dist folder. Open ./dist/index.html to launch Swagger UI in a browser

Browser not supported