build-artifact-versioning.md

+# Using nexus to determine the next version / build number.
+
+By way of listing specific requirements and/or why we need the REST api, here's our use case.
+
+When we build products, like everyone else using maven, we use a X.Y.Z numbering scheme.
+
+Most people use the Jenkins build number for the Z when they are using CD. Or, they use the maven release plugin. But we do neither.
+
+We view nexus as the 'single source of truth' about what versions are there. So what we do is to run a small script before each build that asks nexus what the current, latest version of the artifact is in nexus, then, we increment that number to do the next build.
+
+This provides a number of advantages:
+   * we dont have a bunch of commits for each build [ maven release plugin]
+   * if the build fails, we dont skip version numbers-- we'll only consume a version number when we actually deploy
+   * multiple builds on multiple branches dont get screwed up
+
+I should mention that the 2.X api was not ideal for us to accomplish this. We need to find the latest version of a particular GA coordinate.  We found that neither none of these endpoints worked for us, which would have been a single call:
+
+/service/local/artifact/maven
+/service/local/artifact/maven/content
+/service/local/artifact/maven/resolve
+
+These supported a v=latest value, but would fail when the project was a pom-only project or when i didnt know the jar file i wanted, etc. 
+
+We ended up brute forcing it with this endpoint:
+
+/service/local/lucene/search
+
+with this endpoint, we can find all of the artifiacts for a given GA coordinate, and then find the latest. But the results of this endpoint didnt make it easy for us to do it at all:
+
+  * the data structure did not contain a timestamp, 
+  * the endpoint doesnt allow explicitly ordering the results in any particular order
+
+We ended up just listing all of the artifacts, and ASSUMING that they were listed in newest-to-oldest order, which happens to work. 
+
+In short, what would be great is if the NX3 rest api makes it easy to answer the question: 'what is the current, latest version of an artifact with a GA coordinate?
\ No newline at end of file