Maybe I'm missing something, but I removed any custom exception handlers in favor of what is being done in the commons jar:

https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-commons-spring/src/main/java/org/zowe/commons/spring/CustomRestExceptionHandler.java

For "403" I get the following response:

{
    "messages": [
        {
            "messageType": "ERROR",
            "messageNumber": "ZWEAS403",
            "messageContent": "The user is not authorized to the target resource: Access is denied",
            "messageKey": "org.zowe.commons.rest.forbidden",
            "messageInstanceId": "11a3da12-4895-42b5-81b1-e8e5e092c88d"
        }
    ]
}

For "405" I get no payload response? For us, its really not a big deal to have a message in the response body, the HTTP status is enough, but just wanted to check if this is expected behavior?

As a developed of a REST API (and the SDK too), I would like the integration tests to be counted into code coverage.

1. Local integration tests collect the test coverage from the running Java process
2. z/OS integration tests collect the test coverage from the running Java process

Note: https://www.eclemma.org/jacoco/trunk/doc/agent.html

It requires #24 to be on master and then go to https://bintray.com/beta/#/plavjanik/zowe/zowe-rest-api-commons-spring?tab=overview and use action Add to JCenter.

• Try to use a similar format in the C/C++ code
• Ideally, put the function/macro to the commons library

2019-09-03 04:02:37.856 <ZWEASA1:main:33950015> PLAPE03 (org.zowe.commons.spring.ServiceStartupEventHandler:25) INFO Zowe Sample API Service has been started in 10.204 seconds
[DEBUG] Input - id: 1 content: Hello, world!```

How will we share example makefile for site specific build process for links like object code identifiers?

As the SDK developer, I would like the CIt to build the native code on z/OS.

Acceptance criteria:

• The .so files are built by the CircleCI calling zowe-api-dev against river.zowe.org

Migrate the code for security context switching on z/OS

Depends on #4

The original source code has been added by https://github.gwd.broadcom.net/MFD/ca-sample-restapi-service/pull/28

As a developer who is developing REST API service, I want to run Java code under the same user ID the s user using REST API, so that the code can access mainframe resources only accessible by that user without the need to setup PassTickets.

Original acceptance criteria:

• It is possible to run some Java code under the mainframe security environment for the user that is authenticated to the REST API
• This is done without requiring PassTickets to be set up by leveraging pthread_security_applid_np() function with function code __DAEMON_SECURITY_ENV that requires permission to BPX.DAEMON
• It requires being executed on z/OS, on PC or Mac a dummy implementation can be used

Migrate relevant documentation from https://docops.ca.com/display/IWM/Building+New+APIs to Markdown in the repository or to GitHub wiki (in case of general documentation that is not affected by code changes)

• https://docops.ca.com/display/IWM/Sample+REST+API+Service
• https://docops.ca.com/display/IWM/Using+the+Sample+Service
• https://docops.ca.com/display/IWM/Adding+Error+Messages
• https://docops.ca.com/display/IWM/Adding+Swagger+Annotations
• https://docops.ca.com/display/IWM/Integrating+with+the+API+Mediation+Layer
• https://docops.ca.com/display/IWM/Encrypting+With+HTTPS
• Deprecate original documentation

For "production" APIs we want support for messages presented to the external user in multiple languages.

We need an example "callable" endpoint in the SDK tested against all three security subsystems (modeled after wrapRunnableInEnvironmentForAuthenticatedUser) and understand why one appears to need BPX.DAEMON and the other does not on Top Secret

The packages that are not the sample service code are distributed as Java libraries. They are now kept for practical reasons with the sample.

• Published to Maven Central
• Code of the libraries moved to the https://github.com/zowe/api-layer monorepo
• Spring (package org.zowe.sdk.spring) and non-spring (other packages under org.zowe.sdk) libraries should be created

Needs to consider work on #3 and #4

As a developer of the REST API, I would like to test or debug my REST API on z/OS without losing focus while waiting minutes for JAR or native code upload to finish.

• Smart upload (only changed files - tool remembers the last uploaded file)
• Smart JAR update (only changed files in a JAR are transferred and updated on z/OS) - it can save

The PlatformAccessControl class and its underlying implementation __check_resource_auth_np() support the general resources only. In particular, the class can not specify DATASET.

But checking access to DATASET can be useful.

Acceptance criteria:

• The PlatformSecurityService implementation works well with DATASET resource class and can be used to check access to MVS datasets.

Implementation tips:

• Use assembler code that calls RACROUTE REQUEST=AUTH macro
• Call the assembler code from new JNI function in the zowe-sdk-secur module. This module is program-controlled so it can use RACROUTE REQUEST=AUTH functionality

It might make sense to include some jzos stuff in the sample? It's probably pretty common for folks to need those capabilities.

As a developer of the REST API, I would like to protect REST API endpoints or parts of my code by SAF resources.

• API to do authorization checks
• Check that the application has required permissions for authentication at startup
• Authorization implementation using the Java SAF APIs (DATASET resource class is not in the scope of this story)
• Integration with Spring Security
  • See https://www.baeldung.com/spring-security-create-new-custom-security-expression - 5. A New Security Expression - implement new methods hasSafResourceAccess (absolute class resource name) and hasSafServiceResourceAccess (relative to the user-configurable resource class and resource name prefix for the service)

As an API developer, I would like to be able to localize the Swagger documentation that my API is generating.

• It is possible to define localization for text in the Springfox annotations
• The localization is chosen by the Accept-Language header or lang query parameter
• Validation that Swagger UI component does not prevent the flow of Accept-Language header from the browser to the API service
• Swagger UI component localization is not part of the story

• Try to find out what was wrong (missing .so, missing program-controlled attributed, missing executable attribute, invalid format)

Spring Boot requires JARs inside the fat JAR to be stored without compression.

Caused by: java.lang.IllegalStateException: Unable to open nested entry 'BOOT-INF/lib/zowe-rest-api-commons-spring-0.0.0-SNAPSHOT.jar'. It has been compressed and nested jar files must be stored without compression. Please check the mechanism used to create your executable jar file

The workaround is to use:

zowe-api-dev deploy --force

Full error log:

Starting application in SSH z/OS UNIX session using command '/sys/java64bt/v8r0m0/usr/lpp/java/J8.0_64/bin/java -Djava.library.path="./lib:${LIBPATH}" -Xquickstart -jar bin/zowe-rest-api-sample-spring.jar --spring.config.additional-location=file:etc/application.yml' in directory '/a/plape03/zowe-rest-api-sample-spring'
ℹ You can stop it using Ctrl+C
Executing z/OS UNIX command '/sys/java64bt/v8r0m0/usr/lpp/java/J8.0_64/bin/java -Djava.library.path="./lib:${LIBPATH}" -Xquickstart -jar bin/zowe-rest-api-sample-spring.jar --spring.config.additional-location=file:etc/application.yml' in directory /a/plape03/zowe-rest-api-sample-spring

$ Exception in thread "main" java.lang.IllegalStateException: Failed to get nested archive for entry BOOT-INF/lib/zowe-rest-api-commons-spring-0.0.0-SNAPSHOT.jar
        at org.springframework.boot.loader.archive.JarFileArchive.getNestedArchive(JarFileArchive.java:108)
        at org.springframework.boot.loader.archive.JarFileArchive.getNestedArchives(JarFileArchive.java:87)
        at org.springframework.boot.loader.ExecutableArchiveLauncher.getClassPathArchives(ExecutableArchiveLauncher.java:69)
        at org.springframework.boot.loader.Launcher.launch(Launcher.java:50)
        at org.springframework.boot.loader.JarLauncher.main(JarLauncher.java:52)
Caused by: java.io.IOException: Unable to open nested jar file 'BOOT-INF/lib/zowe-rest-api-commons-spring-0.0.0-SNAPSHOT.jar'
        at org.springframework.boot.loader.jar.JarFile.getNestedJarFile(JarFile.java:258)
        at org.springframework.boot.loader.jar.JarFile.getNestedJarFile(JarFile.java:244)
        at org.springframework.boot.loader.archive.JarFileArchive.getNestedArchive(JarFileArchive.java:104)
        ... 4 more
Caused by: java.lang.IllegalStateException: Unable to open nested entry 'BOOT-INF/lib/zowe-rest-api-commons-spring-0.0.0-SNAPSHOT.jar'. It has been compressed and nested jar files must be stored without compression. Please check the mechanism used to create your executable jar file
        at org.springframework.boot.loader.jar.JarFile.createJarFileFromFileEntry(JarFile.java:284)
        at org.springframework.boot.loader.jar.JarFile.createJarFileFromEntry(JarFile.java:266)
        at org.springframework.boot.loader.jar.JarFile.getNestedJarFile(JarFile.java:255)
        ... 6 more
Error: empty JSON response from Zowe CLI
    at zoweSync (~/workspace/github.com/zowe/sample-spring-boot-api-service/zowe-api-dev/src/zowe.ts:65:23)
    at execSshCommand (~/workspace/github.com/zowe/sample-spring-boot-api-service/zowe-api-dev/src/zowe.ts:152:12)
    at Object.execSshCommandWithDefaultEnv (~/workspace/github.com/zowe/sample-spring-boot-api-service/zowe-api-dev/src/zowe.ts:161:12)
    at Start.run (~/workspace/github.com/zowe/sample-spring-boot-api-service/zowe-api-dev/src/commands/start.ts:59:13)
    at Start._run (~/workspace/github.com/zowe/sample-spring-boot-api-service/zowe-api-dev/node_modules/@oclif/command/lib/command.js:44:31)

We need a way how to let other teams (REST API Sample users) know that this repo has changed (eg vulnerability fix) so they update they code accordingly.

This is an outcome of architecture discussion on 6/24/2019

When adding the zos profile to configuration and calling native code through JNI, you get UnsatisfiedLinkError during invocation. When starting through JCL, messages like this appear in the job log:

08.14.25 JOB51197  TSS7003W Password Will Expire on 07/01/19                                
08.14.25 JOB51197  TSS7000I xxxxxxx Last-Used 26 Jun 19 06:23 System=xxxx Facility=ZOSMF    
08.14.25 JOB51197  TSS7001I Count=00423 Mode=Fail Locktime=None Name=KELOSKY, DANIEL L      
08.14.25 JOB51197  BPXP015I HFS PROGRAM ./libwtojni.so IS NOT MARKED PROGRAM CONTROLLED.    
08.14.25 JOB51197  TSS7236E ENVIRONMENT IS CONTROLLED - UNIX MARK UNCONTROLLED REQUEST RE   
08.14.25 JOB51197  JECTED                                                                   
08.14.25 JOB51197  BPXP014I ENVIRONMENT MUST REMAIN CONTROLLED FOR DAEMON (BPX.DAEMON) PR   
08.14.25 JOB51197  OCESSING.                                                                

Removing the zos from the profile "resolves" the UnsatisfiedLinkError.

• Migrate the documentation about message format to the documentation of the sample service
• Provide practical instructions and examples of how to use it in the following scenarios:
  • Response for the REST API with errors and warnings
  • How to add a new message
  • How to throw exceptions in the code and how to convert them to REST API responses (PetControllerExceptionHandler.java which provides a recommended style)
  • Provide links to good tutorials about error handling in Spring and Java
  • An internal message is written to the server log
    • Improve the generating of the message instance ID (directly in the ApiMessage class)

The API doc states:
"Unexpected errors does not need to be handled or caught by your REST controller. If your controller throws an Exception or RuntimeException then Spring exception handler (customized by CustomRestExceptionHandler in the commons library) will convert the exception into a standardized format. "

Is information available on what content is produced by the commons package for an uncaught exception? For example, does it produce a stack trace, or other detailed information?

Reported by @gejohnston

The goal of this story is to enable developers who are using the SDK to use token-based authentication in their REST API services.

• The SDK commons library is enhanced to provide a self-contained token functionality that follows the requirements is documented in https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/docs/api-client-authentication.md#token-based-authentication
• The token is valid only for the service itself in case of the self-contained implementation
• The same API can be used for token-based authentication with Zowe APIML provider (ZAAS)

Note:

• Start simple - no JWT, just cryptographically safe randoms string, initially in-memory, later persisted
• This is the building block for APIML-based authentication when the basic self-contained provider is replaced by calls to ZAAS just by the means of the API service configuration

Requires #80

For basic auth we will use Java_org_zowe_sdk_zos_security_jni_Secur_createSecurityEnvironment JNI method which does not require BPX.DAEMON access.

If we follow this:

   routes:
        - gatewayUrl: api/v1
          serviceUrl: /api/v1

We may have an endpoint outside of the API ML that is: /api/v1/status.

Then, through the API ML, we would then have /api/v1/servicename/status

A concern is that this might make it difficult to be a client for both cases. Is that valid or is this normal in an API ML?

In an old instance of the SDK, there was a context path, so endpoints were something like:
/sampleservice/api/v1/.... Is the guidance to not have this context path in the URI?

• Automatically publish on tagged builds
• Improve Java doc so it has all useful methods documented and has useful index page

As a developer who is creating an API service, I would like to see an example of the JNI code that is calling MVS code via JNI and OS linkage together with instructions how to build them and run them on z/OS.

The existing code with JNI in the old sample should be migrated to the new sample.

As a developer of the REST API, I would like to know how to do the i18n easily and consistently with other Broadcom products.

• A way how to define i18n for strings in the code
• A way how to define i18n for numbered messages (ErrorService)
• A method of how the required locale is provided to the REST API is defined and propagated the code that is getting the strings or messages, ideally with a little coding
• A method how the service default locale is defined/configured and used in the threads that are not connected to a REST API request
• Greeting endpoint is localized
• Server messages are localized
• Czech or other localization is provided (for testing purposes)
• Swagger documentation - defined as a new story - #73

The current recommendation is that zowe REST API SDK be consumed by importing a single JAR.

While importing one single JAR file may be convenient for some consumers, importing one single JAR file has several disadvantages.

We would like to request that the zowe REST API SDK be able to be consumed in smaller chunks. Instead of a single JAR, we would like the ability to consume only those portions of the SDK which we intend to actively leverage at the present time.

As a developer of Zowe REST API, I would like to be able to run e2e REST API tests easily against my local instance and against z/OS instance.

Acceptance criteria:

• Example of appropriate REST integration tests are added (only a test that makes sense to do as an integration test and not as a unit test only)
• The tests are executed during the CI build (locally on Linux in CircleCI)
• The REST API integration tests are run against the sample API deployed to z/OS

As this repository contains sample source code intended to be downloaded and expanded upon, it would be better suited with an EPL+Apache 2.0 dual license.

The OMP Governing Board has approved EPL-2.0 license waivers for sample repositories in Zowe, replaced by the dual license.

To re-license this repository, all contributors should consent by responding to this issue in the affirmative.

• display executed command java -jar .... - added to #24
• add -d <port> for remote debug of java application

We have code in our service that registers to the API layer. We modeled it after the provided sample:

https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/src/main/java/org/zowe/sample/apiservice/zowe/RegisterToApiLayer.java

Would it be possible (or make sense) to include this with Zowe commons jar?

Because I could not find a way to supply optional properties like messageReason and messageAction to the error-handling capabilities supplied by the commons package, I simply have not used them.

Can you confirm if this is true?

Reported by @gejohnston

As an SDK user, I want to run java code under the same user ID the s user using REST API, so that the code can access mainframe resources only accessible by that user by leveraging future PassTicket support in Zowe to allow me to have a minimum security requirement for my service.

Acceptance Criteria:

• It is possible to run some Java code under the mainframe security environment for the user that is authenticated to the REST API via Zowe Authentication and Authorization Service
• This is done by using requiring PassTickets in Zowe and passing them to pthread_security_applid_np() function with function code __CREATE_SECURITY_ENV that requires permission to BPX.SERVER but not to BPX.DAEMON
• It requires being executed on z/OS, on PC or Mac a dummy implementation can be used

Migrated original story: https://rally1.rallydev.com/#/106710376756d/detail/userstory/288640296608

Tooling that simplifies localization and checks its correctness and can generate a message reference for numbered error messages.

• Create a new zowe-api-dev messages i18n command that will:

  • Create a new localization file - messages_{languageCode}.properties initialized with non-localized and commented text from messages.yml that needs to be localized
  • Checks that existing localization files messages_{languageCode}.properties have all the messages keys covered. This will help developers to find out that a localization is missing for a new message
  • Checks that existing localization does not have any extra keys starting with messages.. To find out extra localization for keys that were removed/renamed in messages.yml

• New zowe-api-dev messages docgen:

  • Uses @jandadav's docgen approach that generates a Markdown document that can be used in Zowe documentation with a message reference

Reporting for another team - SafPlatformUser() does not reject a valid user name with a blank password when called through the SDK basic auth code.

I haven't had a chance to independently verify but capturing here until it is verified.

I'm not sure if there was a change in the repo or in Chrome, but when I attempt to see the swagger UI for a service deployed to z/OS in by browser I now get this error (which I can no longer bypass in Chrome):

Has there been some change to cause this?

• Move errors and rest.response packages from zowe/api-layer to the commons - resolved by #36

• Follow the same request and response format as API Catalog
• https://zowe.org/docs-site/latest/extend/extend-apiml/api-mediation-security.html#security-service-client-library

We would like the SDK to require only BPX.SERVER (instead of BPX.DAEMON & superuser)

I am toying with zowe samples. While trying out one, I got this error

Mounting zFS filesystem USERID.ZOWE.SAMPLAPI.ZFS to /a/surgo01/zowe-rest-api-sample-spring
Executing z/OS UNIX command '/usr/sbin/mount -v -o aggrgrow -f USERID.ZOWE.SAMPLAPI.ZFS /a/userid/zowe-rest-api-sample-spring'
Error: 
$ FOMF0504I mount error: 8B 119B00B0
USERID.ZOWE.SAMPLAPI.ZFS
EPERM: The operation is not permitted 
JRUserNotPrivileged: The requester of the service is not privileged 

how do i get past this?

Steps:

1. Use http protocol to connect
2. Following message is displayed:

2019-10-05 15:59:06.400 <ZWEASA1:https-jsse-nio-0.0.0.0-20081-exec-1:33620312> SDKBLD1 (org.apache.coyote.http11.Http11NioProtocol:175) ERROR Error reading request, ignored
java.lang.NullPointerException: null
        at org.apache.tomcat.util.net.NioEndpoint$NioSocketWrapper.getSslSupport(NioEndpoint.java:1392)
        at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:853)
        at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1593)
        at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1160)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635)
        at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
        at java.lang.Thread.run(Thread.java:811)

Expected behavior:

• No error message and no stack trace in the log

Message is not correct:
Run ./gradlew zosbuild in directory C:\dev\java\sample-spring-boot-api-service\zowe-rest-api-commons-spring

It should be:
It should be: run ./gradlew :zowe-rest-api-commons-spring:zosbuild in C:\dev\java\sample-spring-boot-api-service

Reported by @dkelosky