Skip to main content

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 cached in the maven-central proxy 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:

Example Response

{
  "items" : [    
    {
      "id": "bWF2ZW4tcHVibGljOmEwYmE4MmI",
      "repository": "maven-public",
      "format": "maven2",
      "group": "org.apache.maven.plugins",
      "name": "maven-resources-plugin",
      "version": "2.6",
      "assets": [
        {
          "downloadUrl": "https://stage.repo.sonatype.com/repository/maven-public/org/apache/maven/plugins/maven-resources-plugin/2.6/maven-resources-plugin-2.6.jar",
          "path": "/org/apache/maven/plugins/maven-resources-plugin/2.6/maven-resources-plugin-2.6.jar",
          "id": "bWF2ZW4tcHVibGljOmY3ZmRiYWE5",
          "repository": "maven-public",
          "format": "maven2",
          "checksum": {
            "md5": "e7cc4bbb6888e6c9dd5acdad08cf4bd3",
            "sha1": "dd093ff6a4b680eae7ae83b5ab04310249fc6590"
          },
          "contentType": "application/java-archive",
          "lastModified": "2020-04-29T15:20:19.336+00:00",
          "lastDownloaded": "2022-06-07T09:38:51.841+00:00",
          "uploader": "anonymous",
          "uploaderIp": "192.168.0.0",
          "fileSize": 29519,
          "blobCreated": "2020-04-29T15:20:19.336+00:00",
          "blobStoreName": null,
          "maven2": {
            "extension": "jar",
            "groupId": "org.apache.maven.plugins",
            "artifactId": "maven-resources-plugin",
            "version": "2.6"
          }
        },
        {
          "downloadUrl": "https://stage.repo.sonatype.com/repository/maven-public/org/apache/maven/plugins/maven-resources-plugin/2.6/maven-resources-plugin-2.6.pom",
          "path": "/org/apache/maven/plugins/maven-resources-plugin/2.6/maven-resources-plugin-2.6.pom",
          "id": "bWF2ZW4tcHVibGljOmE4ZTFmZGNj",
          "repository": "maven-public",
          "format": "maven2",
          "checksum": {
            "md5": "6a372cccaee82ea1d63b191a49349e70",
            "sha1": "5db5c3a879f31e8de7b580c79a52b245454c4620"
          },
          "contentType": "application/xml",
          "lastModified": "2020-04-29T15:20:18.689+00:00",
          "lastDownloaded": "2022-06-07T09:38:42.142+00:00",
          "uploader": "anonymous",
          "uploaderIp": "192.168.0.0",
          "fileSize": 8115,
          "blobCreated": "2020-04-29T15:20:18.689+00:00",
          "blobStoreName": null,
          "maven2": {
            "extension": "pom",
            "groupId": "org.apache.maven.plugins",
            "artifactId": "maven-resources-plugin",
            "version": "2.6"
          }
        }
      ],
      "tags": []
    },
...
  ],
  "continuationToken" : "88491cd1d185dd136f143f20c4e7d50c"
}
This endpoint uses a pagination strategy that can be used to iterate through all the components if desired. As of release 3.74.0, pagination defaults to showing 100 items at a time; this setting is not configurable.
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'
Example Response
{
  "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.
Example Maven jar Component Upload With Automatically Created pom File Using curl
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.
Example pom and jar Component Upload Using curl
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
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:
Example Response
HTTP/1.1 204 No Content
Date: Fri, 19 Jan 2018 20:26:13 GMT
...