CODEWITHSUNDEEP
javaapinaming-conventionspackageversioning
Gerald Mücke
Gerald Mücke

Reputation: 11132

Java package naming for versioning external APIs

Are there any conventions of how to name Java packages containing classes that consume an external, versioned API?

Let's assume we have a major-minor semantic versioning scheme of a service and we have to implement a consumer that is compatible with and bound to a specific version of that API. What are the best practices to name the packages (and classes)?

Currently, we're using the scheme of: ${service}_${M}_${N} (with M = Major version, N = minor version). For example: com.example.theService_1_0.. But sonarqube is complaining that it does not match conventions. Of course I can just disable this rule, but I wonder if there are any best-practices?

I'm looking for a general approach not only something specific to REST, because I've encountered consumer implementations for WebService, REST and CORBA. And I'm not sure, artifact-versioning (as in maven) works well here, because it relates to the version of the implementation and not the API.

I know there are questions around api versioning, but those are about the producer, not the consumer.

Upvotes: 2

Views: 3063

Answers (1)

Peter Hilton
Peter Hilton

Reputation: 17344

Yes, Java package names have a strong and ambiguous convention for indicating dependencies’ versions: don’t.

If you change your application to use a new version of an external API, you create a new version of your application. The version number you are looking for is your application’s version number. On many Java projects, dependencies’ versions are management by a Maven configuration file.

In any case, when classes use a particular API version, the class and package names have no business exposing this information, which would violate encapsulation, apart from anything else. These names have a different purpose.

Note that this is no different when you use HTTP/REST APIs or Java APIs. After all, I don’t think you’d name your class TheServiceWithLog4J_12_1_5. I hope not, at least.

You didn’t mention whether you have a requirement to support multiple versions of this external API at the same time. Even if you did, I still wouldn’t recommend exposing the API version number in the package name. Instead, use the package name to indicate why you have two versions, and the important difference.

Upvotes: 1

Related Questions