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" : "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. Pagination defaults to showing 10 items at a time, which cannot currently be changed.

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
...