# 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](https://help.sonatype.com/en/pagination.html "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](https://help.sonatype.com/en/uploading-components.html "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 accept 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 repository. 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
...
```