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 |
maven2.assetN.classifier | String | No | Classifier of the corresponding |
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 |
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 ...