Page Comparison

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

Overview

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.

...

Example project structure:

Customer REST-

...

Webapps pom

...

Example

Code Block

<?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>

...

Info

title	Note

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

Core REST-

...

API pom

...

Example

Code Block

<?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

Code Block

<?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

Code Block

<?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>

Install Tomcat 7

A Tomcat must be installed on your environment.

Info
Make sure to use Apache Tomcat version 7.X.X as version 8 and above does not respect class path order (on which the Rator code relies).

Installation

Info
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.

...

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:
Code Block
language sql
title 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

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

Code Block

language	sql
title	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!

Code Block

title	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:

...

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).

...

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.

...

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).

...

Versions Compared

Old Version 64

New Version 65

Key

Overview

How to

Include the REST

API in

Customer Projects

Customer REST-

Webapps pom

Example

Core REST-

API pom

Example

Customer REST-

API pom

Example

Auth REST-

API pom

Example

Install Tomcat 7

Installation

Database Setup

Verify Deployment

Resources

SVN/GIT

Jenkins

Nexus

Build

rator-rest-api

rator-rest-api-auth

Swagger UI