How do I manage MarkLogic REST endpoint extension versions using gradle?

Question

I'm extending the REST API in MarkLogic and managing my development and deployment using gradle. By default, my endpoint looks like this (note v1):

http://localhost:8005/v1/resources/my_endpoint

If I change my endpoint implementation, how do I expose the new version as v2 and keep the original (v1) for backward compatibility so that I have

http://localhost:8005/v2/resources/my_endpoint

using gradle? I don't see any way to annotate version in my gradle config files. I've been searching MarkLogic's gradle wiki and haven't found an answer there.

Answer 1

I was able to meet requirement using a declarative rewriter as @rjrudin suggested.

I started by copying <MarkLogic install dir>\Modules\MarkLogic\rest-api\rewriter.xml to api-rewriter.xml, modifying the new file, and updating my rest api server Url Rewriter value (via Admin console).

Then I added the following declarations:

<match-path matches="^/api">
    <match-method any-of="GET">
        <match-path matches="/(v\d+\.\d+)/([\w|\-]+)/(\d+)">
            <set-query-param name="name">$1_$2</set-query-param>
            <set-query-param name="rs:id">$3</set-query-param>
            <dispatch>/MarkLogic/rest-api/endpoints/resource-service-query.xqy</dispatch>
        </match-path>
        <match-path matches="/(v\d+\.\d+)/(\w+)">
            <set-query-param name="name">$1_$2</set-query-param>
            <dispatch>/MarkLogic/rest-api/endpoints/resource-service-query.xqy</dispatch>
        </match-path>
    </match-method>
</match-path>

I create resource implementations using ml-gradle with names that look like this: v2.0_ping.sjs. So now I can use urls like this:

http://{{host}}:{{port}}/api/v2.0/ping

that resolve to

/MarkLogic/rest-api/endpoints/resource-service-query.xqy?name=v2.0_ping

Answer 2

The REST API unfortunately doesn't allow for what you want - see https://docs.marklogic.com/REST/PUT/v1/config/resources/[name] . You can specify a version as optional metadata on your extension, but that will not change the URL - it's still going to be "/v1/resources/my_endpoint".

You however can achieve this if you customize the default XML rewriter that MarkLogic uses for a REST API app server - see https://docs.marklogic.com/guide/app-dev/XMLrewriter .