More secure exception mappers

From now on, all exception mappers in jersey-support module of the SDK that deal with exceptions coming from Jersey are no longer including the exception's message in the HTTP response body, instead static messages will be included. That assures that no internal system information will be leaked outside your service, as long as you are using our library. Do not worry about loosing the exception information, the exception will be now logged in every exception mapper.

If you are instantiating any of those exceptions manually with a message that you want to see in response body, you need to provide a custom exception together with an exception mapper for that case.

User in metric logs

We continue to improve metric logging in Service SDK. Now the current user can be included in every metric log. For more information, see the updated schema-log. In order to use this feature, the user property must be present in the MDC context.

Improved control over JSON serialization/deserialization

It is now possible to customize serialization and deserialization of JSON entities by configuring the JsonFeature included in the Service SDK. For example, you can now easily enable inclusion of empty value properties in serialization which is needed for a Jersey client which makes partial update requests.

Api Console security improvement

The Api Console library which can be embedded in your service, will now load only RAML files which reside underneath the service's base URL.

Support for exposing your service's RAML at the recommended fixed URL

The Service SDK now supports services which expose the RAML API definition at the 'meta-data/api.raml' relative URL. Exposing the RAML at a well-defined fixed URL which can be easily resolved relative to the base-URL of the service itself makes services more accessible to API consumers which would be then able to easily locate the service's API definition entry point.

As a result we have adjusted the Api-Console and the Service Generator to follow this convention by default and to locate the RAML file at the new fixed location instead of locating it by parsing the now deprecated api-listings.json file.

Artifacts created with the updated archetype will also automatically follow the convention.

Migration guide

To benefit from the advantages of following the fixed RAML URL convention, your service needs some adjustments.

For a Java service which used the previous SDK version you can follow these steps:

####Step 1: The Api-listings.json file has been deprecated and you need to move all information contained here to the Service Generator Plugin configuration.

In the project's pom.xml you need to locate the 'service-sdk-generator-maven-plugin' and update the configuration of the execution with the 'generate-service' goal.

replace

 <inputFolder>src/main/resources/api</inputFolder>

with

<inputFolder>src/main/webapp/meta-data</inputFolder>

####Step 2: Take values from the 'src/main/resources/api/api-listings.json and add them to the plugin configuration as follows:

Example result:

<execution>
    <id>service-generation</id>
    <goals>
        <goal>generate-service</goal>
    </goals>
    <configuration>
        <outputPackageName>com.hybris.configuration.rest.resources</outputPackageName>
        <outputApiTitle>Configurationservice</outputApiTitle>
        <inputFolders>
            <inputFolder>src/main/webapp/meta-data</inputFolder>
            <inputFolder>target/hybris-api-dependencies</inputFolder>
        </inputFolders>
    </configuration>
</execution>

####Step 3: If there are several APIs defined in the api-listings.json you need to add an execution for each API defined in the api-listings.json file. For each execution make sure you update the 'outputPackageName', 'outputApiTitle', 'async' fields. (repeat step 1 and 2 for each API definition)

Important: Each exection needs to have a different 'id'.

####Step 4: Delete the api-listings.json files from the 'src/main/resources/api' directory

####Step 5: First step to expose the RAML and it's include files as static content is by moving/renaming the /src/main/resources/api folder to /src/main/webapp/meta-data

####Step 6: The main RAML file needs to be renamed to api.raml All secondary RAML files can keep their original name.

####Step 7: (optional but recommended) It is encouraged to follow certain conventions for structuring and naming the additional resources. According to these conventions, the following relative URL paths and file suffixes should be used:

####Step 8: Register the 'default' filter to 'serve' the new 'meta-data' folder and also register the SDK's Raml Rewriter filter by adding the following files to the web.xml:

    <!-- Add RAML rewriting to static RAML resources that are part of the service 
        meta-data -->
    <filter>
        <filter-name>ramlRewriterFilter</filter-name>
        <filter-class>com.sap.cloud.yaas.servicesdk.ramlrewriter.filter.RamlRewriterFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>ramlRewriterFilter</filter-name>
        <url-pattern>/meta-data/*</url-pattern>
    </filter-mapping>

    <!-- Make sure that static meta-data are being served normally -->
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/meta-data/*</url-pattern>
    </servlet-mapping>

####Step 9: Rebuild the Maven project (mvn clean install)

Backwards compatibility

To mantain backwards compatibility and to give enough time to your service's consumers to update to the latest RAML URL you may adjust your service to expose the RAML API descriptor at both the current URL and the new fixed URL simultaneously by following these steps:

####Step 1: In web.xml, map the RamlRewriterFilter (and the default Servlet) to additional URL pattern /api-console/raml/*.

    <filter-mapping>
        <filter-name>ramlRewriterFilter</filter-name>
        <url-pattern>/meta-data/*</url-pattern>
        <url-pattern>/api-console/raml/*</url-pattern>
    </filter-mapping>

    <!-- Make sure that static meta-data are being served normally -->
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/meta-data/*</url-pattern>
        <url-pattern>/api-console/raml/*</url-pattern>
    </servlet-mapping>

####Step 2: In pom.xml, make sure that the build copies all RAML API resources to the /api-console/raml/api/ directory in the WAR file and also renames api.raml to its service specific name. (make sure you replace 'YOUR_ORIGINAL_RAML_FILE_NAME_HERE' as appropiate.

<plugin>
    <artifactId>maven-antrun-plugin</artifactId>
    <executions>
        <execution>
            <id>package-raml-backward-compatibility</id>
            <goals>
                <goal>run</goal>
            </goals>
            <phase>prepare-package</phase>
            <configuration>
                <tasks>
                    <copy todir="${project.build.directory}/${project.build.finalName}/api-console/raml/api">
                        <fileset dir="src/main/webapp/meta-data" excludes="api.raml"/>
                    </copy>
                    <copy tofile="${project.build.directory}/${project.build.finalName}/api-console/raml/api/YOUR_ORIGINAL_RAML_FILE_NAME_HERE.raml"
                            file="src/main/webapp/meta-data/api.raml"/>
                </tasks>
            </configuration>
        </execution>
    </executions>
</plugin>