Components API

Introduction

This set of endpoints is for interacting with components directly.

Endpoints

List Components

GET /service/rest/v1/components

This endpoint allows us to iterate through a listing of components contained in a given repository.

Let's get a listing of the components in the maven-central repository:

curl -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/components?repository=maven-central'

Typically this will produce a response that is the first page of many components in that repository, as such:

{
  "items" : [ {
    "id" : "bWF2ZW4tY2VudHJhbDo4ODQ5MWNkMWQxODVkZDEzNjMyNjhmMjIwZTQ1ZDdkZQ",
    "repository" : "maven-central",
    "format" : "maven2",
    "group" : "com.google.guava",
    "name" : "guava",
    "version" : "21.0",
    "assets" : [ {
      "downloadUrl" : "http://localhost:8081/repository/maven-central/com/google/guava/guava/21.0/guava-21.0.jar",
      "path" : "com/google/guava/guava/21.0/guava-21.0.jar",
      "id" : "bWF2ZW4tY2VudHJhbDozZjVjYWUwMTc2MDIzM2I2MzA4OThiZjZmZTFkOTE2NA",
      "repository" : "maven-central",
      "format" : "maven2",
      "checksum" : {
        "sha1" : "3a3d111be1be1b745edfa7d91678a12d7ed38709",
        "md5" : "ddc91fd850fa6177c91aab5d4e4d1fa6"
      }
    }, {
      "downloadUrl" : "http://localhost:8081/repository/maven-central/com/google/guava/guava/21.0/guava-21.0.jar.sha1",
      "path" : "com/google/guava/guava/21.0/guava-21.0.jar.sha1",
      "id" : "bWF2ZW4tY2VudHJhbDpmODk4YjM5MDNjYjk5YzU5MDc0MDFlYzRjNjVlNjU5OQ",
      "repository" : "maven-central",
      "format" : "maven2",
      "checksum" : {
        "sha1" : "a1ff60cb911e1f64801c03d03702044d10c9bdd3",
        "md5" : "e34b8695ede1677ba262411d757ea980"
      }
    }, {
      "downloadUrl" : "http://localhost:8081/repository/maven-central/com/google/guava/guava/21.0/guava-21.0.pom",
      "path" : "com/google/guava/guava/21.0/guava-21.0.pom",
      "id" : "bWF2ZW4tY2VudHJhbDpkMDY0ODA0YThlZDVhZDZlOWJjNDgzOGE1MzM2OGZlZg",
      "repository" : "maven-central",
      "format" : "maven2",
      "checksum" : {
        "sha1" : "fe4fa08a8c0897f9896c7e278fb397ede4a2feed",
        "md5" : "5c10f97af2ce9db54fa6c2ea6997a8d7"
      }
    }, {
      "downloadUrl" : "http://localhost:8081/repository/maven-central/com/google/guava/guava/21.0/guava-21.0.pom.sha1",
      "path" : "com/google/guava/guava/21.0/guava-21.0.pom.sha1",
      "id" : "bWF2ZW4tY2VudHJhbDplMDE4OGVkMDcyOGZhNjhmZDA3NDdkNjlhZDNmZjI5Nw",
      "repository" : "maven-central",
      "format" : "maven2",
      "checksum" : {
        "sha1" : "992b43ab7b3a061be47767e910cab58180325abc",
        "md5" : "33aed29aa0bb4e03ea7854066a5b4738"
      }
    } ]
  },
...
  ],
  "continuationToken" : "88491cd1d185dd136f143f20c4e7d50c"
}

This endpoint uses a pagination strategy that can be used to iterate through all the components if desired.

Note that the ordering of the components is consistent across multiple queries and it is not alphabetical.

Get Component

GET /service/rest/v1/components/{id}

This endpoint allows us to get details about an individual component.

curl -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/components/bWF2ZW4tY2VudHJhbDo4ODQ5MWNkMWQxODVkZDEzNjYwYmUwMjE1MjI2NGUwZQ'

{
  "id" : "bWF2ZW4tY2VudHJhbDo4ODQ5MWNkMWQxODVkZDEzNjYwYmUwMjE1MjI2NGUwZQ",
  "repository" : "maven-central",
  "format" : "maven2",
  "group" : "org.apache.httpcomponents",
  "name" : "httpcomponents-client",
  "version" : "4.3.5",
  "assets" : [ {
    "downloadUrl" : "http://localhost:8081/repository/maven-central/org/apache/httpcomponents/httpcomponents-client/4.3.5/httpcomponents-client-4.3.5.pom",
    "path" : "org/apache/httpcomponents/httpcomponents-client/4.3.5/httpcomponents-client-4.3.5.pom",
    "id" : "bWF2ZW4tY2VudHJhbDozZjVjYWUwMTc2MDIzM2I2YTFhOGUxOGQxZmFkOGM3Mw",
    "repository" : "maven-central",
    "format" : "maven2",
    "checksum" : {
      "sha1" : "95d80a44673358a5dcbcc2f510770b9f93fe5eba",
      "md5" : "f4769c4e60799ede664414c26c6c5c9d"
    }
  }, {
    "downloadUrl" : "http://localhost:8081/repository/maven-central/org/apache/httpcomponents/httpcomponents-client/4.3.5/httpcomponents-client-4.3.5.pom.sha1",
    "path" : "org/apache/httpcomponents/httpcomponents-client/4.3.5/httpcomponents-client-4.3.5.pom.sha1",
    "id" : "bWF2ZW4tY2VudHJhbDpmODk4YjM5MDNjYjk5YzU5ZDU3YjFlYjE0MzM1ZTcwMQ",
    "repository" : "maven-central",
    "format" : "maven2",
    "checksum" : {
      "sha1" : "6b98f5cef5d7102f8f45215bdcf48dc843d060af",
      "md5" : "f3b3ac640853fcb887621d13029a1747"
    }
  } ]
}

Upload Component

POST /service/rest/v1/components

This endpoint allows us to upload a component to a specified repository. Some formats allow to include multiple assets in a single component (please refer to Uploading Components and more information below).

curl -v -u admin:admin123 -X POST 'http://localhost:8081/service/rest/v1/components?repository=maven-releases' -F maven2.groupId=com.google.guava -F maven2.artifactId=guava -F maven2.version=24.0-jre -F maven2.asset1=@guava-24.0-jre.jar -F maven2.asset1.extension=jar -F maven2.asset2=@guava-24.0-jre-sources.jar -F maven2.asset2.classifier=sources -F maven2.asset2.extension=jar

A successful upload will return no content, as follows:

HTTP/1.1 204 No Content
Date: Fri, 19 Jan 2018 20:26:13 GMT
...

The parameters expected by the endpoint depend on the format of the repository where we are going to upload our component.

Maven

Maven format allows multiple assets to be uploaded as part of a single component. To upload multiple assets just follow the information from a table describing the given format and replace assetN with multiple instances of it (e.g. asset1, asset2, etc.):

Field name	Field type	Required?	Description
maven2.groupId	String	Yes, unless a POM asset is included in the upload	Group ID of the component
maven2.artifactId	String	Yes, unless a POM asset is included in the upload	Artifact ID of the component
maven2.version	String	Yes, unless a POM asset is included in the upload	Version of the component
maven2.generate-pom	Boolean	No	Whether the Nexus Repository Manager should generate a POM file based on above component coordinates provided
maven2.packaging	String	No	Define component packaging (e.g. jar, ear)
maven2.assetN	File	Yes, at least one	Binary asset
maven2.assetN.extension	String	Yes	Extension of the corresponding `assetN` asset
maven2.assetN.classifier	String	No	Classifier of the corresponding `assetN` asset

Examples

Uploading a jar and Automatically Creating a pom File

For this example we have a single jar file from a third-party vendor and no project POM file from that third party. We have decided our own Maven 2 coordinates and will ask Nexus to automatically generate and store a POM file for us.

curl -v -u admin:admin123 -F "maven2.generate-pom=true" -F "maven2.groupId=com.example" -F "maven2.artifactId=commercial-product" -F "maven2.packaging=jar" -F "version=1.0.0" -F "maven2.asset1=@/absolute/path/to/the/local/file/product.jar;type=application/java-archive" -F "maven2.asset1.extension=jar" "http://localhost:8081/service/rest/v1/components?repository=maven-third-party"

maven2.generate-pom=true tells Nexus to generate a minimal POM file for us based on the groupId, artifactId, version and packaging we provide
replace "admin:admin123" with your own valid username:password
replace "/absolute/path/to/the/local/file/product.jar " with the local path to the file you are uploading, however leave the leading @ so that curl understands how to find this file
;type=application/java-archive is optional
the repository maven-third-party must already exist or there will be an error
-v makes the command verbose to help you verify a successful response is returned. Otherwise you wouldn't be able to easily tell if it worked or returned an HTTP error code

Upload a POM and associated JAR File

For this example we have a single jar file and we have already created a minimal project pom.xml which includes groupId, artifactId, version elements defined inside of it. Nexus will acccept both the POM and jar file in a single upload operation, and will parse the Maven 2 coordinates from the uploaded POM file and install the artifacts to the correct locations inside the maven-releases respository. Notice how the command need not specify the Maven coordinates.

curl -v -u admin:admin123 -F "maven2.generate-pom=false" -F "maven2.asset1=@/absolute/path/to/the/local/file/pom.xml" -F "maven2.asset1.extension=pom" -F "maven2.asset2=@/absolute/path/to/the/local/file/product-1.0.0.jar;type=application/java-archive" -F "maven2.asset2.extension=jar" "http://localhost:8081/service/rest/v1/components?repository=maven-releases"

APT

Field name	Field type	Required?	Description
apt.asset	File	Yes	Binary asset

Docker

Field name	Field type	Required?	Description
docker.asset	File	Yes	Binary asset

Helm

Field name	Field type	Required?	Description
helm.asset	File	Yes	Binary asset

npm

Field name	Field type	Required?	Description
npm.asset	File	Yes	Binary asset

NuGet

Field name	Field type	Required?	Description
nuget.asset	File	Yes	Binary asset

PyPI

Field name	Field type	Required?	Description
pypi.asset	File	Yes	Binary asset

R

Field name	Field type	Required?	Description
r.asset	File	Yes	Binary asset

Raw

Raw supports uploading multiple assets within a request

Field name	Field type	Required?	Description
raw.directory	String	Yes	Destination for upload files (e.g. /path/to/files)
raw.assetN	File	Yes, at least one	Binary asset
raw.assetN.filename	String	Yes	Filename to be used for the corresponding `assetN` asset

RubyGems

Field name	Field type	Required?	Description
rubygems.asset	File	Yes	Binary asset

Delete Component

DELETE /service/rest/v1/components/{id}

This endpoint can be used to delete an individual component along with the associated assets.

curl -u admin:admin123 -X DELETE 'http://localhost:8081/service/rest/v1/components/bWF2ZW4tY2VudHJhbDo4ODQ5MWNkMWQxODVkZDEzNjYwYmUwMjE1MjI2NGUwZQ'

A successful deletion will return no content, as follows:

HTTP/1.1 204 No Content
Date: Fri, 19 Jan 2018 20:26:13 GMT
...