Skip to content

Commit 400409f

Browse files
fmarco76fmarco76
committed
Add REST API v1 build-time control with runtime deprecation
Introduce build-time flag to exclude v1 REST API code and dependencies, with optional runtime control for managing v1 deprecation when included. Build-time Control: - New --without-apiv1 flag in build.sh to exclude v1 code from build - Default: v1 REST API included (backward compatible) - When excluded: v1 source files not compiled, JAX-RS/RESTEasy dependencies skipped, binary RPMs ~2-3MB smaller - Maven property api.v1=true/false controls profile activation - Profile api-v1-deps includes JAX-RS/RESTEasy/Jackson-JAX-RS dependencies - Profile api-v1-dropped excludes v1 source files via maven-compiler-plugin Runtime Control (when v1 built): - Three runtime states: enabled, deprecated (default), disabled - System property api.v1.status controls behavior at runtime - Can be set per-instance via tomcat.conf or per-subsystem via CS.cfg - ApiStatusHelper centralizes status checking across all subsystems - Input validation: trims, lowercases, rejects invalid values Runtime States: 1. enabled: v1 fully functional, no warnings 2. deprecated (default): v1 functional with startup warnings and standard Deprecation headers (IETF draft-dalal-deprecation-header) 3. disabled: v1 returns HTTP 404 Not Found with clean JSON error response, includes Deprecation Implementation: - base/pom.xml: api-v1-dropped profile for source exclusion - base/common/pom.xml: api-v1-deps profile for conditional dependencies - base/javadoc/CMakeLists.txt: Exclude v1 REST packages from javadoc - pki.spec: Conditional BuildRequires/Requires, %post JAR cleanup - build.sh: --without-apiv1 flag, passes to CMake and RPM - ApiStatusHelper: Shared utility for status validation and handling - ApiDisabledResource: JAX-RS catch-all returning HTTP 410 Gone - ApiDeprecationFilter: JAX-RS response filter adding standard headers - All Application classes updated to use ApiStatusHelper HTTP Standards Compliance: - Deprecation header for deprecated state - Link header (RFC 8288) pointing to v2 API documentation - Separate HTTP method handlers per JAX-RS specification RPM Build: - build.sh: ./build.sh --without-apiv1 rpm - rpmbuild: rpmbuild --without apiv1 -ba pki.spec - Spec validates bcond and sets build_api_v1 conditional - Maven receives -Dapi.v1=true/false based on bcond Migration Path: - Default: v1 included at build, deprecated at runtime (warnings) - Gradual: Configure runtime disabled to enforce v2 migration - Final: Build with --without-apiv1 to remove v1 code permanently Documentation: docs/changes/v11.10.0/Packaging-Changes.adoc and Server-Changes.adoc Assisted-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 40d9178 commit 400409f

27 files changed

Lines changed: 762 additions & 72 deletions

File tree

‎.github/workflows/python-ca-test.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,28 @@ jobs:
427427
428428
diff expected output
429429
430+
####################################################################################################
431+
# Check API v1 status
432+
433+
- name: Check API v1 are deprecated
434+
run: |
435+
docker exec pki curl -v -k https://pki.example.com:8443/pki/v1/info 2>&1 |tee output
436+
grep "< Deprecation: true" output
437+
grep '< Link: <https://github.com/dogtagpki/pki/wiki/REST-API-v2>; rel="alternate"' output
438+
439+
- name: Make the API v1 disabled
440+
run: |
441+
docker exec pki sed -i \
442+
's/-Dredhat.crypto-policies=false/-Dredhat.crypto-policies=false -Dapi.v1.status=disabled/' \
443+
/etc/sysconfig/pki-tomcat
444+
445+
docker exec pki pki-server restart --wait
446+
447+
- name: Check API v1 are disabled
448+
run: |
449+
docker exec pki curl -k https://pki.example.com:8443/pki/v1/info | tee output
450+
grep '"error":"REST API v1 have been disabled"' output
451+
430452
- name: Check DS server systemd journal
431453
if: always()
432454
run: |

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ option(WITH_THEME "Build theme package" ON)
6464
option(WITH_META "Build meta package" ON)
6565
option(WITH_TESTS "Build tests package" ON)
6666
option(RUN_TESTS "Run unit tests" ON)
67+
option(WITH_APIV1 "Build API V1" ON)
6768

6869
set(APPLICATION_VERSION "${APPLICATION_VERSION_MAJOR}.${APPLICATION_VERSION_MINOR}.${APPLICATION_VERSION_PATCH}")
6970

‎base/ca/CMakeLists.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,15 @@ add_custom_command(
7878
COMMAND ln -sf ../../../../../lib/slf4j-jdk14.jar webapp/lib/slf4j-jdk14.jar
7979
COMMAND ln -sf ../../../../../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-server.jar webapp/lib/pki-server.jar
8080
COMMAND ln -sf ../../../../../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-ca.jar webapp/lib/pki-ca.jar
81+
)
82+
83+
if(WITH_APIV1)
84+
add_custom_command(
85+
TARGET pki-ca-links POST_BUILD
86+
COMMAND ${CMAKE_COMMAND} -E make_directory webapp/lib
8187
COMMAND ln -sf ../../../../../server/common/lib/resteasy-servlet-initializer.jar webapp/lib/resteasy-servlet-initializer.jar
8288
)
89+
endif()
8390

8491
if(WITH_JAVA)
8592
install(

‎base/ca/src/main/java/org/dogtagpki/server/ca/rest/v1/CAApplication.java‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
package org.dogtagpki.server.ca.rest.v1;
22

3+
import com.netscape.cmscore.apps.CMSEngine;
34
import java.util.LinkedHashSet;
45
import java.util.Set;
56

67
import javax.ws.rs.ApplicationPath;
78
import javax.ws.rs.core.Application;
9+
import org.dogtagpki.server.ca.CAEngine;
10+
import org.dogtagpki.server.ca.CAEngineConfig;
811

912
import org.dogtagpki.server.rest.v1.ACLInterceptor;
1013
import org.dogtagpki.server.rest.v1.AccountService;
@@ -19,6 +22,7 @@
1922
import org.dogtagpki.server.rest.v1.SelfTestService;
2023
import org.dogtagpki.server.rest.v1.SessionContextInterceptor;
2124
import org.dogtagpki.server.rest.v1.UserService;
25+
import org.dogtagpki.server.rest.v1.ApiStatusHelper;
2226

2327
@ApplicationPath("/v1")
2428
public class CAApplication extends Application {
@@ -30,6 +34,12 @@ public class CAApplication extends Application {
3034

3135
public CAApplication() {
3236

37+
CMSEngine engine = CAEngine.getInstance();
38+
// Check v1 API status
39+
if (ApiStatusHelper.checkApiStatus("CA", classes, logger, engine.getConfig())) {
40+
return;
41+
}
42+
3343
// account
3444
classes.add(AccountService.class);
3545

‎base/common/CMakeLists.txt‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,6 @@ add_custom_command(
128128
COMMAND ln -sf ${JACKSON_ANNOTATIONS_LINK} lib/jackson-annotations.jar
129129
COMMAND ln -sf ${JACKSON_CORE_LINK} lib/jackson-core.jar
130130
COMMAND ln -sf ${JACKSON_DATABIND_LINK} lib/jackson-databind.jar
131-
COMMAND ln -sf ${JACKSON_JAXRS_BASE_LINK} lib/jackson-jaxrs-base.jar
132-
COMMAND ln -sf ${JACKSON_JAXRS_JSON_PROVIDER_LINK} lib/jackson-jaxrs-json-provider.jar
133131
COMMAND ln -sf ${JACKSON_MODULE_JAXB_ANNOTATIONS_LINK} lib/jackson-module-jaxb-annotations.jar
134132
COMMAND ln -sf ${JAKARTA_ACTIVATION_API_LINK} lib/jakarta.activation-api.jar
135133
COMMAND ln -sf ${JAKARTA_ANNOTATION_API_LINK} lib/jakarta.annotation-api.jar
@@ -141,13 +139,23 @@ add_custom_command(
141139
COMMAND ln -sf ../../../..${P11_KIT_TRUST} lib/p11-kit-trust.so
142140
COMMAND ln -sf ../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-common.jar lib/pki-common.jar
143141
COMMAND ln -sf ../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-tools.jar lib/pki-tools.jar
144-
COMMAND ln -sf ${RESTEASY_JACKSON_PROVIDER_LINK} lib/resteasy-jackson2-provider.jar
145-
COMMAND ln -sf ${RESTEASY_JAXRS_LINK} lib/resteasy-jaxrs.jar
146142
COMMAND ln -sf ../../../..${SERVLET_JAR} lib/servlet.jar
147143
COMMAND ln -sf ${SLF4J_API_LINK} lib/slf4j-api.jar
148144
COMMAND ln -sf ${SLF4J_JDK14_LINK} lib/slf4j-jdk14.jar
149145
)
150146

147+
if(WITH_APIV1)
148+
add_custom_command(
149+
TARGET pki-lib POST_BUILD
150+
COMMAND ${CMAKE_COMMAND} -E make_directory lib
151+
COMMAND test ! -d ${CMAKE_SOURCE_DIR}/base/common/lib || cp ${CMAKE_SOURCE_DIR}/base/common/lib/* lib
152+
COMMAND ln -sf ${JACKSON_JAXRS_BASE_LINK} lib/jackson-jaxrs-base.jar
153+
COMMAND ln -sf ${JACKSON_JAXRS_JSON_PROVIDER_LINK} lib/jackson-jaxrs-json-provider.jar
154+
COMMAND ln -sf ${RESTEASY_JACKSON_PROVIDER_LINK} lib/resteasy-jackson2-provider.jar
155+
COMMAND ln -sf ${RESTEASY_JAXRS_LINK} lib/resteasy-jaxrs.jar
156+
)
157+
endif()
158+
151159
add_custom_target(pki-man ALL
152160
COMMENT "Creating PKI manuals")
153161

‎base/common/pom.xml‎

Lines changed: 50 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -94,12 +94,6 @@
9494
<version>4.0.0</version>
9595
</dependency>
9696

97-
<dependency>
98-
<groupId>org.jboss.spec.javax.ws.rs</groupId>
99-
<artifactId>jboss-jaxrs-api_2.0_spec</artifactId>
100-
<version>1.0.0.Final</version>
101-
</dependency>
102-
10397
<dependency>
10498
<groupId>com.fasterxml.jackson.core</groupId>
10599
<artifactId>jackson-annotations</artifactId>
@@ -124,36 +118,6 @@
124118
<version>2.14.2</version>
125119
</dependency>
126120

127-
<dependency>
128-
<groupId>com.fasterxml.jackson.jaxrs</groupId>
129-
<artifactId>jackson-jaxrs-base</artifactId>
130-
<version>2.14.2</version>
131-
</dependency>
132-
133-
<dependency>
134-
<groupId>com.fasterxml.jackson.jaxrs</groupId>
135-
<artifactId>jackson-jaxrs-json-provider</artifactId>
136-
<version>2.14.2</version>
137-
</dependency>
138-
139-
<dependency>
140-
<groupId>org.jboss.logging</groupId>
141-
<artifactId>jboss-logging</artifactId>
142-
<version>3.4.1.Final</version>
143-
</dependency>
144-
145-
<dependency>
146-
<groupId>org.jboss.resteasy</groupId>
147-
<artifactId>resteasy-jaxrs</artifactId>
148-
<version>3.0.26.Final</version>
149-
</dependency>
150-
151-
<dependency>
152-
<groupId>org.jboss.resteasy</groupId>
153-
<artifactId>resteasy-jackson2-provider</artifactId>
154-
<version>3.0.26.Final</version>
155-
</dependency>
156-
157121
<dependency>
158122
<groupId>org.dogtagpki.jss</groupId>
159123
<artifactId>jss-base</artifactId>
@@ -168,6 +132,56 @@
168132

169133
</dependencies>
170134

135+
<profiles>
136+
<!-- Include API v1 dependencies unless skipped -->
137+
<profile>
138+
<id>api-v1-deps</id>
139+
<activation>
140+
<property>
141+
<name>api.v1</name>
142+
<value>true</value>
143+
</property>
144+
</activation>
145+
<dependencies>
146+
<dependency>
147+
<groupId>org.jboss.spec.javax.ws.rs</groupId>
148+
<artifactId>jboss-jaxrs-api_2.0_spec</artifactId>
149+
<version>1.0.0.Final</version>
150+
</dependency>
151+
152+
<dependency>
153+
<groupId>com.fasterxml.jackson.jaxrs</groupId>
154+
<artifactId>jackson-jaxrs-base</artifactId>
155+
<version>2.14.2</version>
156+
</dependency>
157+
158+
<dependency>
159+
<groupId>com.fasterxml.jackson.jaxrs</groupId>
160+
<artifactId>jackson-jaxrs-json-provider</artifactId>
161+
<version>2.14.2</version>
162+
</dependency>
163+
164+
<dependency>
165+
<groupId>org.jboss.logging</groupId>
166+
<artifactId>jboss-logging</artifactId>
167+
<version>3.4.1.Final</version>
168+
</dependency>
169+
170+
<dependency>
171+
<groupId>org.jboss.resteasy</groupId>
172+
<artifactId>resteasy-jaxrs</artifactId>
173+
<version>3.0.26.Final</version>
174+
</dependency>
175+
176+
<dependency>
177+
<groupId>org.jboss.resteasy</groupId>
178+
<artifactId>resteasy-jackson2-provider</artifactId>
179+
<version>3.0.26.Final</version>
180+
</dependency>
181+
</dependencies>
182+
</profile>
183+
</profiles>
184+
171185
<build>
172186
<plugins>
173187
<plugin>

‎base/javadoc/CMakeLists.txt‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,37 @@ if(((${Javadoc_VERSION_MAJOR} EQUAL 1) AND (${Javadoc_VERSION_MINOR} EQUAL 8)) O
5656
set(doclintstr "-Xdoclint:none")
5757
endif()
5858

59+
if(WITH_APIV1)
60+
# v1 enabled/deprecated/disabled: include all packages
61+
message(STATUS "API v1: including all packages in javadoc")
62+
set(v1_subpackages "com.netscape.certsrv" "org.dogtagpki")
63+
set(exclude_packages "")
64+
set(jaxrs_classpath ${JAXRS_API_JAR} ${RESTEASY_JAXRS_JAR})
65+
set(v1_javadoc_opts "")
66+
else()
67+
# v1 dropped: exclude v1-specific packages from javadoc
68+
message(STATUS "API v1 dropped: excluding v1 packages from javadoc")
69+
# Don't include com.netscape.certsrv or org.dogtagpki (which are mostly v1 Resource interfaces)
70+
set(v1_subpackages "org.dogtagpki")
71+
# Exclude v1-specific packages (both client and server)
72+
# Only exclude v1 REST packages, not entire subsystem packages
73+
set(exclude_packages
74+
"com.netscape.certsrv"
75+
"com.netscape.cms.servlet"
76+
"org.dogtagpki.server.rest.v1"
77+
"org.dogtagpki.server.ca.rest.v1"
78+
"org.dogtagpki.server.kra.rest.v1"
79+
"org.dogtagpki.server.ocsp.rest.v1"
80+
"org.dogtagpki.server.tks.rest.v1"
81+
"org.dogtagpki.server.tps.rest.v1"
82+
)
83+
# Don't include JAX-RS jars - they're not available when v1 is dropped
84+
# and javadoc will skip type checking for excluded packages
85+
set(jaxrs_classpath "")
86+
# Ignore source errors in excluded packages (transformed code references jakarta.ws.rs but jars have javax.ws.rs)
87+
set(v1_javadoc_opts "--ignore-source-errors")
88+
endif()
89+
5990
javadoc(pki-javadoc
6091
SOURCEPATH
6192
${CMAKE_SOURCE_DIR}/base/common/src/main/java
@@ -65,24 +96,24 @@ javadoc(pki-javadoc
6596
${CMAKE_CURRENT_BINARY_DIR}/javadoc/pki
6697
SUBPACKAGES
6798
com.netscape.cmsutil
68-
com.netscape.certsrv
6999
com.netscape.cmstools
70-
org.dogtagpki
100+
${v1_subpackages}
71101
${PKI_JAVADOC_SUBPACKAGES}
102+
EXCLUDE
103+
${exclude_packages}
72104
CLASSPATH
73105
${SLF4J_API_JAR} ${JAXB_API_JAR}
74106
${COMMONS_CLI_JAR} ${COMMONS_LANG3_JAR}
75107
${COMMONS_CODEC_JAR} ${COMMONS_IO_JAR}
76108
${LDAPJDK_JAR}
77109
${SERVLET_JAR} ${TOMCAT_CATALINA_JAR} ${TOMCAT_UTIL_JAR}
78110
${HTTPCLIENT_JAR} ${HTTPCORE_JAR}
79-
${JAXRS_API_JAR}
111+
${jaxrs_classpath}
80112
${JACKSON_CORE_JAR}
81113
${JACKSON_ANNOTATIONS_JAR}
82114
${JACKSON_DATABIND_JAR}
83115
${JACKSON_MODULE_JAXB_ANNOTATIONS_JAR}
84116
${JAKARTA_ANNOTATION_API_JAR}
85-
${RESTEASY_JAXRS_JAR}
86117
${JSS_JAR}
87118
${JSS_TOMCAT_JAR}
88119
${JSS_TOMCAT_9_0_JAR}
@@ -98,6 +129,7 @@ javadoc(pki-javadoc
98129
-version
99130
-quiet
100131
${doclintstr}
132+
${v1_javadoc_opts}
101133
)
102134

103135
add_dependencies(javadoc pki-javadoc)

‎base/kra/CMakeLists.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,16 @@ add_custom_command(
7070
COMMAND ln -sf ../../../../../lib/slf4j-jdk14.jar webapp/lib/slf4j-jdk14.jar
7171
COMMAND ln -sf ../../../../../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-server.jar webapp/lib/pki-server.jar
7272
COMMAND ln -sf ../../../../../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-kra.jar webapp/lib/pki-kra.jar
73+
74+
)
75+
76+
if(WITH_APIV1)
77+
add_custom_command(
78+
TARGET pki-kra-links POST_BUILD
79+
COMMAND ${CMAKE_COMMAND} -E make_directory webapp/lib
7380
COMMAND ln -sf ../../../../../server/common/lib/resteasy-servlet-initializer.jar webapp/lib/resteasy-servlet-initializer.jar
7481
)
82+
endif()
7583

7684
if(WITH_JAVA)
7785
install(

‎base/kra/src/main/java/org/dogtagpki/server/kra/rest/v1/KRAApplication.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
package org.dogtagpki.server.kra.rest.v1;
22

3+
import com.netscape.cmscore.apps.CMSEngine;
34
import java.util.LinkedHashSet;
45
import java.util.Set;
56

67
import javax.ws.rs.ApplicationPath;
78
import javax.ws.rs.core.Application;
89

10+
import org.dogtagpki.server.kra.KRAEngine;
911
import org.dogtagpki.server.rest.v1.ACLInterceptor;
1012
import org.dogtagpki.server.rest.v1.AccountService;
1113
import org.dogtagpki.server.rest.v1.AuditService;
@@ -18,6 +20,7 @@
1820
import org.dogtagpki.server.rest.v1.SelfTestService;
1921
import org.dogtagpki.server.rest.v1.SessionContextInterceptor;
2022
import org.dogtagpki.server.rest.v1.UserService;
23+
import org.dogtagpki.server.rest.v1.ApiStatusHelper;
2124

2225
@ApplicationPath("/v1")
2326
public class KRAApplication extends Application {
@@ -29,6 +32,12 @@ public class KRAApplication extends Application {
2932

3033
public KRAApplication() {
3134

35+
CMSEngine engine = KRAEngine.getInstance();
36+
// Check v1 API status
37+
if (ApiStatusHelper.checkApiStatus("KRA", classes, logger, engine.getConfig())) {
38+
return;
39+
}
40+
3241
// account
3342
classes.add(AccountService.class);
3443

‎base/ocsp/CMakeLists.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,8 +68,15 @@ add_custom_command(
6868
COMMAND ln -sf ../../../../../lib/slf4j-jdk14.jar webapp/lib/slf4j-jdk14.jar
6969
COMMAND ln -sf ../../../../../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-server.jar webapp/lib/pki-server.jar
7070
COMMAND ln -sf ../../../../../../../..${JAVA_JAR_INSTALL_DIR}/pki/pki-ocsp.jar webapp/lib/pki-ocsp.jar
71+
)
72+
73+
if(WITH_APIV1)
74+
add_custom_command(
75+
TARGET pki-ocsp-links POST_BUILD
76+
COMMAND ${CMAKE_COMMAND} -E make_directory webapp/lib
7177
COMMAND ln -sf ../../../../../server/common/lib/resteasy-servlet-initializer.jar webapp/lib/resteasy-servlet-initializer.jar
7278
)
79+
endif()
7380

7481
if(WITH_JAVA)
7582
install(

0 commit comments

Comments
 (0)