Search code examples
javarestjerseyjax-rsmicroservices

REST api service context and resources url

We have serveral services running on an application server and every service has a context. The name of the service is automatically added to the url, since there can be multiple services on the same application server.
Now we are creating a new service, which is called Draws, meaning the url will be

http://url:port/Draws

However, now the discussion is the api paths (Resources) to this service. Since we are getting draws, in my mind this should be draws. Which means it will have the url

http://url:port/Draws/draws/{gameNo}

2x draws - Thoughts?

There are thoughts here that the service does only have draws and therefor Draws/{gameNo} is enough.
But in my mind, draws resource is the api interface of the service, like Draws is the book in a library, draws is the chapter... And it should be possible to add more chapters to the book.

Then to implementation, we are using Jersey. That would mean we would have a resource with @Path("{gameNo}").

Edit 1:
There are gateways in front of our services, so the context will never be exposed to end users, it's only there to point to an specific service. Since multiple services can run on the same host:port

Edit 2:
Context part of the url is part of the service discovery lookup

Edit 3:
We are actually not versioning in url, but in Accept header, so actually my url is the same as clementinos but the version part of the url

Solution

  • I would avoid using 2x 'draws'.

    Here is a possible way to design the URI structure. Please note, that segments should be lower case (so don't use 'Draws')

    <scheme>://<host>[:<port>]/<api-path>/<api-name>/<api-version>/<resource-path>
    • scheme (eg. http)
    • host is a fully qualified hostname, a DNS alias hiding the equipment and physical location of the API implementation. It contains information about the environment when it is a non-productive environment (test, int).
    • port should be the default http port (80) and thus can be omitted. Other ports can be used for non-productive environments.
    • api path separates the REST API from other resources served by the server (e.g. a webapp). It is usually of the form /api. For servers serving only REST apis, it can be omitted.
    • api name gathers a set of resources in a kind of package. This is the unit of publishing and versioning.
    • api version is the version of the API. It has the form v[major-version-number]
    • resource path is composed of the resource URI segments