GET /rest/v1/softwaremodules

Implementation notes

Handles the GET request of retrieving all softwaremodules within SP. Required Permission: READ_REPOSITORY

Get software modules

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules' -i -X GET

Request URL

GET /rest/v1/softwaremodules HTTP/1.1
Host: management-api.host.com

Request parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/softwaremodules?offset=1&limit=2&sort=version%3ADESC&q=name%3D%3DSM* HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

total

Number

Total number of elements

size

Number

Current page size

content

Array

List of software modules.

content[].id

Number

The technical identifier of the entity

content[].name

String

The name of the entity

content[].description

String

The description of the entity

content[].vendor

String

The software vendor.

content[].createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

content[].createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

content[].lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

content[].lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

content[].type

String

The software module type of the entity

content[].version

String

Package version.

Response example

HTTP/1.1 200 OK
Content-Length: 959
Content-Type: application/hal+json;charset=UTF-8

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1582108907389,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1582108907408,
    "name" : "os",
    "description" : "a description",
    "version" : "1.0",
    "type" : "os",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/17"
      }
    },
    "id" : 17
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1582108907424,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1582108907439,
    "name" : "application",
    "description" : "a description",
    "version" : "1.0",
    "type" : "application",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/18"
      }
    },
    "id" : 18
  } ],
  "total" : 2,
  "size" : 2
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/softwaremodules

Implementation notes

Handles the POST request of creating new software modules within SP. The request body must always be a list of modules. Required Permission: CREATE_REPOSITORY

Create software modules

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules' -i -X POST \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '[ {
  "vendor" : "vendor1",
  "name" : "name1",
  "description" : "description1",
  "type" : "os",
  "version" : "version1"
}, {
  "vendor" : "vendor1",
  "name" : "name3",
  "description" : "description1",
  "type" : "application",
  "version" : "version1"
} ]'

Request URL

POST /rest/v1/softwaremodules HTTP/1.1
Content-Length: 261
Content-Type: application/hal+json;charset=UTF-8
Host: management-api.host.com

[ {
  "vendor" : "vendor1",
  "name" : "name1",
  "description" : "description1",
  "type" : "os",
  "version" : "version1"
}, {
  "vendor" : "vendor1",
  "name" : "name3",
  "description" : "description1",
  "type" : "application",
  "version" : "version1"
} ]

Request fields

Path Type Description Allowed Values Mandatory

[]name

String

The name of the entity

X

[]description

String

The description of the entity

[]version

String

Package version.

X

[]vendor

String

The software vendor.

[]type

String

The type of the software module identified by its key.

X

Response (Status 201)

Response fields

Path Type Description Allowed Values

[].id

Number

The technical identifier of the entity

[].name

String

The name of the entity

[].description

String

The description of the entity

[].vendor

String

The software vendor.

[].deleted

Boolean

Deleted flag, used for soft deleted entities

[].createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

[].createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

[].lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

[].lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

[].type

String

The software module type of the entity

[].version

String

Package version.

Response example

HTTP/1.1 201 Created
Content-Length: 807
Content-Type: application/hal+json;charset=UTF-8

[ {
  "createdBy" : "bumlux",
  "createdAt" : 1582108904692,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108904692,
  "name" : "name1",
  "description" : "description1",
  "version" : "version1",
  "type" : "os",
  "vendor" : "vendor1",
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/5"
    }
  },
  "id" : 5
}, {
  "createdBy" : "bumlux",
  "createdAt" : 1582108904698,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108904698,
  "name" : "name3",
  "description" : "description1",
  "version" : "version1",
  "type" : "application",
  "vendor" : "vendor1",
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/4"
    }
  },
  "id" : 4
} ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/softwaremodules/{softwareModuleId}

Implementation Notes

Handles the DELETE request for a single softwaremodule within SP. Required Permission: DELETE_REPOSITORY

Delete software module

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/2' -i -X DELETE

Request URL

DELETE /rest/v1/softwaremodules/2 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Response (Status 200)

Response example

HTTP/1.1 200 OK

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/softwaremodules/{softwareModuleId}

Implementation notes

Handles the GET request of retrieving a single softwaremodule within SP. Required Permission: READ_REPOSITORY

Get software module

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/6' -i -X GET

Request URL

GET /rest/v1/softwaremodules/6 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

description

String

The description of the entity

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

vendor

String

The software vendor.

deleted

Boolean

Deleted flag, used for soft deleted entities

type

String

The software module type of the entity

version

String

Package version.

_links.type

Object

The software module type of the entity

_links.artifacts

Object

List of artifacts of given software module.

_links.metadata

Object

List of metadata.

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 750

{
  "createdBy" : "bumlux",
  "createdAt" : 1582108904999,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108905016,
  "name" : "os",
  "description" : "a description",
  "version" : "1.0",
  "type" : "os",
  "vendor" : "Vendor Limited, California",
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/6"
    },
    "artifacts" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/6/artifacts"
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremoduletypes/13"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/6/metadata?offset=0&limit=50"
    }
  },
  "id" : 6
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

PUT /rest/v1/softwaremodules/{softwareModuleId}

Implementation notes

Handles the PUT request for a single softwaremodule within SP. Required Permission: UPDATE_REPOSITORY

Update software module

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/3' -i -X PUT \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '{
  "vendor" : "another Vendor",
  "description" : "a new description"
}'

Request URL

PUT /rest/v1/softwaremodules/3 HTTP/1.1
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 72
Host: management-api.host.com

{
  "vendor" : "another Vendor",
  "description" : "a new description"
}

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

vendor

String

The software vendor.

description

String

The description of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

description

String

The description of the entity

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

type

String

The software module type of the entity

version

String

Package version.

vendor

String

The software vendor.

deleted

Boolean

Deleted flag, used for soft deleted entities

_links.type

Object

The software module type of the entity

_links.artifacts

Object

List of artifacts of given software module.

_links.metadata

Object

List of metadata.

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 741

{
  "createdBy" : "bumlux",
  "createdAt" : 1582108904246,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108904321,
  "name" : "os",
  "description" : "a new description",
  "version" : "1.0",
  "type" : "os",
  "vendor" : "another Vendor",
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/3"
    },
    "artifacts" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/3/artifacts"
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremoduletypes/8"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/3/metadata?offset=0&limit=50"
    }
  },
  "id" : 3
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/softwaremodules/{softwareModuleId}/artifacts

Implementation notes

Handles the GET request of retrieving all meta data of artifacts assigned to a software module. Required Permission: READ_REPOSITORY

List artifacts metadata

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/16/artifacts' -i -X GET

Request URL

GET /rest/v1/softwaremodules/16/artifacts HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

[].id

Number

The technical identifier of the entity

[].size

Number

Size of the artifact.

[].createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

[].createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

[].lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

[].lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

[].hashes.md5

String

MD5 hash of the artifact.

[].hashes.sha1

String

SHA1 hash of the artifact.

[].hashes.sha256

String

SHA256 hash of the artifact.

[].providedFilename

String

Filename of the artifact.

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 524

[ {
  "createdBy" : "bumlux",
  "createdAt" : 1582108907125,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108907125,
  "hashes" : {
    "sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
    "md5" : "0d1b08c34858921bc7c662b228acb7ba",
    "sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
  },
  "providedFilename" : "file1",
  "size" : 3,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/16/artifacts/2"
    }
  },
  "id" : 2
} ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/softwaremodules/{softwareModuleId}/artifacts

Implementation notes

Handles POST request for artifact upload. Required Permission: CREATE_REPOSITORY

Upload artifact

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/1/artifacts' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@origFilename'

Request URL

POST /rest/v1/softwaremodules/1/artifacts HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: management-api.host.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=origFilename

???
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Request query parameter

Parameter Description

filename

Filename of the artifact.

file

Binary of file.

md5sum

MD5 hash of the artifact.

sha1sum

SHA1 hash of the artifact.

Request parameter example

POST /rest/v1/softwaremodules/15/artifacts HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: management-api.host.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=filename

filename
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file

s
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=md5sum

md5sum
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=sha1sum

sha1sum
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=origFilename

????
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Response (Status 201)

Response fields

Path Type Description Allowed Values

size

Number

Size of the artifact.

id

Number

The technical identifier of the entity

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

_links.download

Object

Download link of the artifact.

hashes.md5

String

MD5 hash of the artifact.

hashes.sha1

String

SHA1 hash of the artifact.

hashes.sha256

String

SHA256 hash of the artifact.

providedFilename

String

Filename of the artifact.

Response example

HTTP/1.1 201 Created
Content-Length: 648
Content-Type: application/hal+json;charset=UTF-8

{
  "createdBy" : "bumlux",
  "createdAt" : 1582108903500,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108903500,
  "hashes" : {
    "sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
    "md5" : "0d1b08c34858921bc7c662b228acb7ba",
    "sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
  },
  "providedFilename" : "origFilename",
  "size" : 3,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/1/artifacts/1"
    },
    "download" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/1/artifacts/1/download"
    }
  },
  "id" : 1
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/softwaremodules/{softwareModuleId}/artifacts/{artifactId}

Implementation Notes

Handles the DELETE request for a single SoftwareModule within SP. Required Permission: DELETE_REPOSITORY

Delete arifact

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/21/artifacts/5' -i -X DELETE

Request URL

DELETE /rest/v1/softwaremodules/21/artifacts/5 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

artifactId

The technical identifier of the entity

Response (Status 200)

Response example

HTTP/1.1 200 OK

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/softwaremodules/{softwareModuleId}/artifacts/{artifactId}

Implementation notes

Handles the GET request of retrieving a single Artifact meta data request. Required Permission: READ_REPOSITORY

Get artifact metadata

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/19/artifacts/3' -i -X GET

Request URL

GET /rest/v1/softwaremodules/19/artifacts/3 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

artifactId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

size

Number

Size of the artifact.

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

hashes.md5

String

MD5 hash of the artifact.

hashes.sha1

String

SHA1 hash of the artifact.

hashes.sha256

String

SHA256 hash of the artifact.

providedFilename

String

Filename of the artifact.

_links.download

Object

Download link of the artifact.

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 643

{
  "createdBy" : "bumlux",
  "createdAt" : 1582108907739,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108907739,
  "hashes" : {
    "sha1" : "3b93fd2d045d59af27a25c719945db1d9fe3decb",
    "md5" : "e94f0bfab8c987a7437ba4e1697c1cc0",
    "sha256" : "5d04c6a96439100ad3cb4672ef2fdc219dae8aaa655c9a3095c9e7ad25f4d96c"
  },
  "providedFilename" : "file1",
  "size" : 4,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/19/artifacts/3"
    },
    "download" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/19/artifacts/3/download"
    }
  },
  "id" : 3
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/softwaremodules/{softwareModuleId}/artifacts/{artifactId}/download

Implementation notes

Handles the GET request for downloading an artifact. Required Permission: READ_REPOSITORY

Download artifact

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/20/artifacts/4/download' -i -X GET \
    -H 'Accept: application/octet-stream'

Request URL

GET /rest/v1/softwaremodules/20/artifacts/4/download HTTP/1.1
Accept: application/octet-stream
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

artifactId

The technical identifier of the entity

Response (Status 200)

Response example

HTTP/1.1 200 OK
Last-Modified: Wed, 19 Feb 2020 10:41:48 GMT
Accept-Ranges: bytes
Content-Range: bytes 0-2/3
Content-Type: application/octet-stream
Content-Disposition: attachment;filename=file1
Content-Length: 3
ETag: 2d86c2a659e364e9abba49ea6ffcd53dd5559f05

???

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/softwaremodules/{softwareModuleId}/metadata

Implementation notes

Get a paged list of meta data for a software module. Required Permission: READ_REPOSITORY

Get a paged list of metadata

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/30/metadata' -i -X GET

Request URL

GET /rest/v1/softwaremodules/30/metadata HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/softwaremodules/27/metadata?offset=1&limit=2&sort=key%3ADESC&q=key%3D%3Dknown* HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

total

Number

Total number of elements

size

Number

Current page size

content

Array

List of metadata.

content[].key

String

Metadata property key.

content[].value

String

Metadata property value.

content[].targetVisible

Boolean

Metadata property is visible to targets as part of software update action.

Response example

HTTP/1.1 200 OK
Content-Length: 405
Content-Type: application/hal+json;charset=UTF-8

{
  "content" : [ {
    "key" : "knownKey0",
    "value" : "knownValue0",
    "targetVisible" : false
  }, {
    "key" : "knownKey1",
    "value" : "knownValue1",
    "targetVisible" : false
  }, {
    "key" : "knownKey2",
    "value" : "knownValue2",
    "targetVisible" : false
  }, {
    "key" : "knownKey3",
    "value" : "knownValue3",
    "targetVisible" : false
  } ],
  "total" : 4,
  "size" : 4
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/softwaremodules/{softwareModuleId}/metadata

Implementation notes

Create a list of meta data entries Required Permission: UPDATE_REPOSITORY

Create a list of metadata entries

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/9/metadata' -i -X POST \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '[ {
  "value" : "knownValue1",
  "key" : "knownKey1"
}, {
  "targetVisible" : true,
  "value" : "knownValue2",
  "key" : "knownKey2"
} ]'

Request URL

POST /rest/v1/softwaremodules/9/metadata HTTP/1.1
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 136
Host: management-api.host.com

[ {
  "value" : "knownValue1",
  "key" : "knownKey1"
}, {
  "targetVisible" : true,
  "value" : "knownValue2",
  "key" : "knownKey2"
} ]

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

[]key

String

Metadata property key.

X

[]value

String

Metadata property value.

X

[]targetVisible

Boolean

Metadata property is visible to targets as part of software update action.

X

Response (Status 201)

Response fields

Path Type Description Allowed Values

[]key

String

Metadata property key.

[]value

String

Metadata property value.

[]targetVisible

Boolean

Metadata property is visible to targets as part of software update action.

Response example

HTTP/1.1 201 Created
Content-Length: 163
Content-Type: application/hal+json;charset=UTF-8

[ {
  "key" : "knownKey1",
  "value" : "knownValue1",
  "targetVisible" : false
}, {
  "key" : "knownKey2",
  "value" : "knownValue2",
  "targetVisible" : true
} ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/softwaremodules/{softwareModuleId}/metadata/{metadataKey}

Implementation Notes

Delete a single meta data. Required Permission: UPDATE_REPOSITORY

Deleting a single metadata

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/33/metadata/knownKey' -i -X DELETE

Request URL

DELETE /rest/v1/softwaremodules/33/metadata/knownKey HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

{metadataKey

Metadata property key.

Response (Status 200)

Response example

HTTP/1.1 200 OK

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/softwaremodules/{softwareModuleId}/metadata/{metadataKey}

Implementation notes

Get a single meta data value for a meta data key. Required Permission: READ_REPOSITORY

Get a single metadata value

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/24/metadata/knownKey' -i -X GET

Request URL

GET /rest/v1/softwaremodules/24/metadata/knownKey HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

metadataKey

Metadata property key.

Response (Status 200)

Response fields

Path Type Description Allowed Values

key

String

Metadata property key.

value

String

Metadata property value.

targetVisible

Boolean

Metadata property is visible to targets as part of software update action.

Response example

HTTP/1.1 200 OK
Content-Length: 77
Content-Type: application/hal+json;charset=UTF-8

{
  "key" : "knownKey",
  "value" : "knownValue",
  "targetVisible" : false
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

PUT /rest/v1/softwaremodules/{softwareModuleId}/metadata/{metadataKey}

Implementation notes

Update a single meta data value for speficic key. Required Permission: UPDATE_REPOSITORY

Updating a single metadata value

CURL

$ curl 'https://management-api.host.com/rest/v1/softwaremodules/14/metadata/knownKey' -i -X PUT \
    -H 'Content-Type: application/hal+json;charset=UTF-8' \
    -d '{
  "targetVisible" : true,
  "value" : "valueForUpdate",
  "key" : "knownKey"
}'

Request URL

PUT /rest/v1/softwaremodules/14/metadata/knownKey HTTP/1.1
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 80
Host: management-api.host.com

{
  "targetVisible" : true,
  "value" : "valueForUpdate",
  "key" : "knownKey"
}

Request path parameter

Parameter Description

softwareModuleId

The technical identifier of the entity

metadataKey

Metadata property key.

Request fields

Path Type Description Allowed Values Mandatory

key

String

Metadata property key.

X

value

String

Metadata property value.

X

targetVisible

Boolean

Metadata property is visible to targets as part of software update action.

X

Response (Status 200)

Response fields

Path Type Description Allowed Values

key

String

Metadata property key.

value

String

Metadata property value.

targetVisible

Boolean

Metadata property is visible to targets as part of software update action.

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 741

{
  "createdBy" : "bumlux",
  "createdAt" : 1582108904246,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1582108904321,
  "name" : "os",
  "description" : "a new description",
  "version" : "1.0",
  "type" : "os",
  "vendor" : "another Vendor",
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/3"
    },
    "artifacts" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/3/artifacts"
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremoduletypes/8"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/softwaremodules/3/metadata?offset=0&limit=50"
    }
  },
  "id" : 3
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Software Module.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

Additional content

Error body

{
  "errorCode": "string",
  "exceptionClass": "string",
  "message": "string",
  "parameters": [
    "string"
  ]
}

Field description

Field

Description

errorCode

A error code/key set by server

exceptionClass

The involved exceptionClass

message

An error message set by the server

parameters

A list of parameters