Page Comparison

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:

...

Example project structure:

...

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

...

1. Retrieve the rator-rest-api .war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build).
2. Retrieve the rator-rest-api-auth.war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build).
3. Copy the war files to the Tomcat webapps directory and (re-)start the Tomcat application.
4. Retrieve the swagger-ui dist folder (either from Github, or from our own repositories, see Resources. Or by building the project yourself, see Build).
5. 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.
6. In your browser, enter the URL "http://<Swagger server and port>/<base-path>/?url=http://<REST server and port>/<base-path>/api/swagger.json". 
7. You should now see a list of the resources available on the REST server.

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

   
   

...

Database Setup

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

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

   
   

...

1. 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.
2. 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.
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.

...

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.

...

• https://bitbucket.org/cdrator/rator-rest-api
• https://bitbucket.org/cdrator/rator-rest-api-auth
• https://bitbucket.org/cdrator/rator-core-api/
• https://svn.cdrator.com/svn/dev/thirdparty/swagger-ui-2.1.1
• https://svngithub.cdrator.com/svn/dev/thirdparty/swagger-api/swagger-ui-3/tree/v3.20.0-src/dist / deploy/dist

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

...

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.

...

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

rator-rest-api-auth

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

...

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

...