Friday, January 26, 2018

Nexus automation API

The Nexus documentation and examples are horribly fragmentary and scattered - I have rarely seen a such popular product being under-documented in this chaotic way.

Since 3.3 there is a Swagger-UI interface http://blog.sonatype.com/nexus-repository-new-beta-rest-api-for-content not available in 2.14 . Try for instance http://nexus-nodejs/swagger-ui/#!/assets/getAssets (replace nexus-nodejs with your own URL)

A quite explanatory article on REST API (including the /nexus/service/local/ vs /nexus/service/siesta story) is http://www.sonatype.org/nexus/2015/01/26/learn-the-nexus-rest-api-automating-sonatype-nexus/

One can always generate a Java Client from Swagger http://www.baeldung.com/spring-boot-rest-client-swagger-codegen or also https://github.com/swagger-api/swagger-codegen

Apparently Nexus chose Groovy as a language for automation https://help.sonatype.com/display/NXRM3/Writing+Scripts

REST syntax


To discover the syntax of the REST calls (with JSON payload) Nexus recommends simply ("request espionage") to use Developer Tools (F12 in IE, CTRL-SHIFT-I in Chrome and Firefox), go to Network tab, start capturing and execute manually some commands in the Administration UI.

This for instance is how to "whitelist" (pre-approve) use of a xml-apis:xml-apis:1.3.04 (GAV) component in the provisioned repository "approved_from_central" :

Request POST /service/local/procurement/resolutions/approved_from_central HTTP/1.1
X-Nexus-UI true
Accept application/json,application/vnd.siesta-error-v1+json,application/vnd.siesta-validation-errors-v1+json
Content-Type application/json
X-Requested-With XMLHttpRequest
Referer http://nexusserver/
Accept-Language de-CH
Accept-Encoding gzip, deflate
User-Agent Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; Ypkch32; rv:11.0) like Gecko
Host nexusserver
Content-Length 170
Connection Keep-Alive
Cache-Control no-cache
Cookie NXSESSIONID=e2265c85-f82b-45ce-a889-f6964cdaa214

Request Body 
{"data":{"artifactCoordinate":{"groupId":"xml-apis","artifactId":"xml-apis","version":"1.3.04"},"properties":[{"key":"isApproved","value":"true"}],"ruleTypeId":"simple"}}




Return code is HTTP 201 (created)


In 2.14 you can get the whole list of APIs by logging in as admin, on the left menu click on Administration, Plugin Console, click on "Nexus Core API (Restlet 1.x Plugin)" (Provides Nexus Core REST API) and click on the Documentation link http://nexusserver/nexus-restlet1x-plugin/default/docs/index.html


This video seems the only serious attempt to document the REST API




Other useful commands:

#get the status of repository (the -u option is not necessary!)
curl -u admin:admin123 http://nexusserver/service/local/status

curl -X GET -u admin:admin123 http://nexusserver/service/local/users

#get list of all repositories, in xml format
curl http://nexusserver/service/local/all_repositories

#get list of all assets with "arquillian" in the name
curl http://nexusserver/service/local/data_index?q=arquillian

curl -i -H "Accept: application/xml" -H "Content-Type: application/xml" -X POST -v -trace-ascii -d "@repository-definition.xml" -u admin:admin123 http://nexusserver/service/local/repositories


See the curl documentation here https://curl.haxx.se/docs/manpage.html#-d



There are several github repositories:

https://github.com/sonatype/nexus-book-examples/tree/nexus-3.x


git clone https://github.com/sonatype/nexus-book-examples.git
cd nexus-book-examples/
git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/NEXUS-14940-deprecate-service-siesta
remotes/origin/master
remotes/origin/nexus-3.x
git checkout -b nexus-3.x origin/nexus-3.x


then open this in your firefox:
file:///home/centos/nexus-book-examples/scripting/apidocs/index.html


The source code is available in https://github.com/sonatype/nexus-public under
plugins/nexus-script-plugin :
https://github.com/sonatype/nexus-public/blob/master/plugins/nexus-script-plugin/src/main/java/org/sonatype/nexus/script/plugin/RepositoryApi.java


To parse XML in Python: https://docs.python.org/2/library/xml.etree.elementtree.html

To make curl requests (POST, GET) in Python: http://docs.python-requests.org/en/master/




Example with Nexus PRO 2.14


cat allowartifact.json
{"data":{"artifactCoordinate":{"groupId":"xml-apis","artifactId":"xml-apis","version":"1.3.04"},"properties":[{"key":"isApproved","value":"true"}],"ruleTypeId":"simple"}}


curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X POST -v -trace-ascii -d "@allowartifact.json" -u admin:admin123 http://nexusserver/service/local/procurement/resolutions/approved_from_central

* About to connect() to nexusserver port 80 (#0)
*   Trying 44.55.66.77... connected
* Connected to nexusserver (44.55.66.77) port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /service/local/procurement/resolutions/approved_from_central HTTP/1.1
> Authorization: Basic YWRteee6cG9qqqV4dXM=
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.27.1 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: nexusserver
> Accept: application/json
> Content-Type: application/json
> Content-Length: 170
> 
< HTTP/1.1 201 Created
HTTP/1.1 201 Created
< Date: Fri, 26 Jan 2018 13:15:17 GMT
Date: Fri, 26 Jan 2018 13:15:17 GMT
< Server: Nexus/2.14.5-02 Noelios-Restlet-Engine/1.1.6-SONATYPE-5348-V8
Server: Nexus/2.14.5-02 Noelios-Restlet-Engine/1.1.6-SONATYPE-5348-V8
< X-Frame-Options: SAMEORIGIN
X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
X-Content-Type-Options: nosniff
< Content-Type: application/json; charset=UTF-8
Content-Type: application/json; charset=UTF-8
< Content-Length: 191
Content-Length: 191
< Cache-Control: no-store, no-cache, must-revalidate, max-age=1, private, proxy-revalidate
Cache-Control: no-store, no-cache, must-revalidate, max-age=1, private, proxy-revalidate
< Expires: Fri, 26 Jan 2018 13:15:17 GMT
Expires: Fri, 26 Jan 2018 13:15:17 GMT
< Pragma: no-cache
Pragma: no-cache
< Connection: close
Connection: close

< 
* Closing connection #0
{"data":{"id":"655124ddf28eb","artifactCoordinate":{"groupId":"xml-apis","artifactId":"xml-apis","version":"1.3.04"},"ruleTypeId":"simple","properties":[{"key":"isApproved","value":"true"}]}}


and this inserts into nexusserver/conf/procurement.xml :


<procuredArtifacts>
 <procuredArtifact>
   <id>655124ddf28eb</id>
   <type>simple</type>
   <groupId>xml-apis</groupId>
   <artifactId>xml-apis</artifactId>
   <version>1.3.04</version>
   <ruleProperties>
  <ruleProperty>
    <key>isApproved</key>
    <value>true</value>
  </ruleProperty>
   </ruleProperties>
 </procuredArtifact>
</procuredArtifacts>



sample CURL calls


#add -H "Accept: application/json" to get in JSON format, otherwise it defaults to XML
#get pom of an artifact
curl "http://nexus-java/service/local/artifact/maven?g=xml-apis&a=xml-apis&v=1.3.04&r=central"
#get all repos
curl http://nexus-java/service/local/all_repositories
#get all components of a given group
curl -H "Accept: application/xml" http://nexus-java/service/local/lucene/search?g=xml-apis


See the documentation of the lucene indexer https://repository.sonatype.org/nexus-indexer-lucene-plugin/default/docs/path__lucene_search.html



No comments: