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 nameField typeRequired?Description
maven2.groupIdStringYes, unless a POM asset is included in the uploadGroup ID of the component
maven2.artifactIdStringYes, unless a POM asset is included in the uploadArtifact ID of the component
maven2.versionStringYes, unless a POM asset is included in the uploadVersion of the component
maven2.generate-pomBooleanNoWhether the Nexus Repository Manager should generate a POM file based on above component coordinates provided
maven2.packagingStringNoDefine component packaging (e.g. jar, ear)
maven2.assetNFileYes, at least oneBinary asset
maven2.assetN.extensionStringYesExtension of the corresponding assetN asset
maven2.assetN.classifierStringNoClassifier 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 nameField typeRequired?Description
apt.assetFileYesBinary asset

Docker

Field nameField typeRequired?Description
docker.assetFileYesBinary asset

Helm

Field nameField typeRequired?Description
helm.assetFileYesBinary asset

npm

Field nameField typeRequired?Description
npm.assetFileYesBinary asset

NuGet

Field nameField typeRequired?Description
nuget.assetFileYesBinary asset

PyPI

Field nameField typeRequired?Description
pypi.assetFileYesBinary asset

R

Field nameField typeRequired?Description
r.assetFileYesBinary asset

Raw

Raw supports uploading multiple assets within a request

Field nameField typeRequired?Description
raw.directoryStringYesDestination for upload files (e.g. /path/to/files)
raw.assetNFileYes, at least oneBinary asset
raw.assetN.filenameStringYesFilename to be used for the corresponding assetN asset

RubyGems

Field nameField typeRequired?Description
rubygems.assetFileYesBinary 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
...