TOSCAna

Base URL: /, Version: 1.0.0-SNAPSHOT

To be Done!

Schemes:

Summary

Tag: csars

Operations for Cloud Service Archives (CSARs)

Operation	Description
GET /api/csars	List all CSARs stored on the server
GET /api/csars/{csarId}/transformations	List all transformations of a CSAR
GET /api/csars/{name}	Returns details for a specific name (identifier)
POST /api/csars/{name}	Creates a new CSAR
PUT /api/csars/{name}	Creates a new CSAR
DELETE /api/csars/{name}/delete	Deletes a Existing CSAR
GET /api/csars/{name}/logs	Get the logs of a csar

Tag: hypermedia

Hypermedia only endpoints

Operation	Description
GET /api/	Hypermedia endpoint to get all resource endpoints
GET /api/status	Hypermedia endpoint to get all supported Status operations

Tag: platforms

Operations for the supported platforms of the transformer

Operation	Description
GET /api/platforms	List all supported Platforms
GET /api/platforms/{id}	Get the Details for a specific Platform

Tag: transformations

Operations regarding Transformations

Operation	Description
GET /api/csars/{csarId}/transformations	List all transformations of a CSAR
GET /api/csars/{csarId}/transformations/{platform}	Get details for a specific transformation
GET /api/csars/{csarId}/transformations/{platform}/artifact	Download the target artifact archive
POST /api/csars/{csarId}/transformations/{platform}/create	Create a new Transformation
PUT /api/csars/{csarId}/transformations/{platform}/create	Create a new Transformation
DELETE /api/csars/{csarId}/transformations/{platform}/delete	Delete a transformation
GET /api/csars/{csarId}/transformations/{platform}/inputs	Retrieve the inputs of this transformation
POST /api/csars/{csarId}/transformations/{platform}/inputs	Set the value of inputs
PUT /api/csars/{csarId}/transformations/{platform}/inputs	Set the value of inputs
GET /api/csars/{csarId}/transformations/{platform}/logs	Get the logs for a Transformation
GET /api/csars/{csarId}/transformations/{platform}/outputs	Retrieve the outputs and their values
POST /api/csars/{csarId}/transformations/{platform}/start	Start a Transformation

Paths

Hypermedia endpoint to get all resource endpoints

GET /api/

Tags: hypermedia

The retuned links to the endpoints are: Csars, platforms and status

application/hal+json

200 OK: OK

ResourceSupport
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: Not Found

List all CSARs stored on the server

GET /api/csars

Tags: csars

Returns a Hypermedia Resource containing all CSARs that have been uploaded to the server and did not get removed

application/hal+json

200 OK: OK

CsarResources
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: Not Found

List all transformations of a CSAR

GET /api/csars/{csarId}/transformations

Tags: csars, transformations

Returns a HAL-Resources list containing all Transformations for a specific CSAR


csarId	The unique identifier for the CSAR	path	string

application/hal+json

200 OK: The operation was executed successfully

TransformationResources
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier

RestErrorResponse

Get details for a specific transformation

GET /api/csars/{csarId}/transformations/{platform}

Tags: transformations

Returns a HAL-Resource Containing the details for the transformation with the given parameters


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully

TransformationResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a Transformation for the specified platform.

RestErrorResponse

Download the target artifact archive

GET /api/csars/{csarId}/transformations/{platform}/artifact

Tags: transformations

Once the transformation is done (in the state DONE) or it has encountered a error (state ERROR). It is possible to download a archive (ZIP format) of all the files generated while the transformation was running.


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/octet-stream

200 OK: The operation was executed successfully
400 Bad Request: There is nothing to download yet because the execution of the transformation has not yet started or is not finished (With or without errors)

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a Transformation for the specified platform.

RestErrorResponse

Create a new Transformation

POST /api/csars/{csarId}/transformations/{platform}/create

Tags: transformations

Creates a new transformation for the given CSAR and Platform (If the platform does not exist and there is no other transformation with the same CSAR and Platform, you have to delete the old transformation in this case)

application/json


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully
201 Created: Created
400 Bad Request: The transfomation could not get created because there already is a Transformation of this CSAR on the given Platform

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the platform is not known.

RestErrorResponse

Create a new Transformation

PUT /api/csars/{csarId}/transformations/{platform}/create

Tags: transformations

application/json


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully
201 Created: Created
400 Bad Request: The transfomation could not get created because there already is a Transformation of this CSAR on the given Platform

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the platform is not known.

RestErrorResponse

Delete a transformation

DELETE /api/csars/{csarId}/transformations/{platform}/delete

Tags: transformations

Deletes a transformation and all the coresponding artifacts


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully
204 No Content: No Content
400 Bad Request: The Deletion of the csar failed
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a Transformation for the specified platform.

RestErrorResponse

Retrieve the inputs of this transformation

GET /api/csars/{csarId}/transformations/{platform}/inputs

Tags: transformations

This Operation returns a list of inputs, specific to the csar and the platform. If the input is invalid it has to be set in order to proceed with starting the transformation. Setting the inputs is done with a POST or PUT to the same URL (See Set Inputs Operation). If Transformation does not have any inputs, an empty array is returned


csarId	The identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully

GetInputsResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a Transformation for the specified platform.

RestErrorResponse

Set the value of inputs

POST /api/csars/{csarId}/transformations/{platform}/inputs

Tags: transformations

With this method it is possible to set the value of an input or multiple inputs at once. The values of inputs can be set as long as they are in the READY or INPUT_REQUIRED state. The transformation changes its state to ready once all required inputs have a valid value assigned to them.

application/json

propertiesRequest

InputsResponse


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/json

200 OK: The operation was executed successfully

InputsResponse
201 Created: Created
400 Bad Request: Inputs cannot get set once the transformation has been started.

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a transformation for the specified platform.

RestErrorResponse
406 Not Acceptable: At least one of the inputs could not get set because either the key does not exist or the syntax validation of the value has failed.

InputsResponse

Set the value of inputs

PUT /api/csars/{csarId}/transformations/{platform}/inputs

Tags: transformations

application/json

propertiesRequest

InputsResponse


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/json

200 OK: The operation was executed successfully

InputsResponse
201 Created: Created
400 Bad Request: Inputs cannot get set once the transformation has been started.

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a transformation for the specified platform.

RestErrorResponse
406 Not Acceptable: At least one of the inputs could not get set because either the key does not exist or the syntax validation of the value has failed.

InputsResponse

Get the logs for a Transformation

GET /api/csars/{csarId}/transformations/{platform}/logs

Tags: transformations

Returns the logs for a transformation, starting at a specific position. from the given start index all following log lines get returned. If the start index is larger than the current last log index the operation will return a empty list.


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string
start	The index of the first log entry you want (0 returns the whole log)	query	integer (int64)

application/hal+json

200 OK: The operation was executed successfully

LogResponse
400 Bad Request: The given start value is less than zero

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a Transformation for the specified platform.

RestErrorResponse

Retrieve the outputs and their values

GET /api/csars/{csarId}/transformations/{platform}/outputs

Tags: transformations

This operation returns the outputs of a deployment. Retrieval of the outputs is not possible if the transformation (including deployment) is not done yet


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully

GetOutputsResponse
400 Bad Request: The state of the transformation is invalid (not ERROR or DONE)

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a transformation for the specified platform

RestErrorResponse

Start a Transformation

POST /api/csars/{csarId}/transformations/{platform}/start

Tags: transformations

Starts a transformation that has been created and is ready to get started. To start a transformation, the Transformation has to be in the state READY otherwise the transformation cannot start.

application/json


csarId	The unique identifier for the CSAR	path	string
platform	The identifier for the platform	path	string

application/hal+json

200 OK: The operation was executed successfully

ResponseEntity
201 Created: Created
400 Bad Request: The state of the transformation is illegal. This means that the transformation is not in theREADY state. Therefore starting it is not possible

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier or the CSAR does not have a Transformation for the specified platform.

RestErrorResponse

Returns details for a specific name (identifier)

GET /api/csars/{name}

Tags: csars

Returns the element with the given name, Object contents are equal to a regular /csars request (if you just look at the desired entry)


name	The unique identifier for the CSAR	path	string

application/hal+json

200 OK: The Csar was found and the contents are found in the body

CsarResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given name (identifier)

RestErrorResponse

Creates a new CSAR

POST /api/csars/{name}

Tags: csars

This operation creates a new CSAR if the name (identifier) is not used already. The uploaded file has to be a valid CSAR archive. Once the file was uploaded the server will synchronously (the client has to wait for the response) unzip the archive and parse it. Upload gets performed using Multipart Form upload.

multipart/form-data


name	The unique identifier for the CSAR	path	string
file	The CSAR Archive (Compressed as ZIP)	formData	file

application/hal+json

200 OK: OK
201 Created: The upload of the csar was successful
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: Not Found
406 Not Acceptable: CSAR upload rejected - given ID already in use
500 Internal Server Error: The server encountered a unexpected problem

Creates a new CSAR

PUT /api/csars/{name}

Tags: csars

multipart/form-data


name	The unique identifier for the CSAR	path	string
file	The CSAR Archive (Compressed as ZIP)	formData	file

application/hal+json

200 OK: OK
201 Created: The upload of the csar was successful
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: Not Found
406 Not Acceptable: CSAR upload rejected - given ID already in use
500 Internal Server Error: The server encountered a unexpected problem

Deletes a Existing CSAR

DELETE /api/csars/{name}/delete

Tags: csars

Deletes the Resulting CSAR and its transformations (if none of them is running). If a transformation is running (in the state TRANSFORMING) the CSAR cannot be deleted


name	The unique identifier for the CSAR	path	string

application/hal+json

200 OK: The deletion of the CSAR was successful
204 No Content: No Content
400 Bad Request: The deletion of the CSAR failed, because there is one or more transformations still running.

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given name (identifier)

RestErrorResponse

Get the logs of a csar

GET /api/csars/{name}/logs

Tags: csars

Returns the logs for a csar, starting at a specific position. from the given start index all following log lines get returned. If the start index is larger than the current last log index the operation will return a empty list.


name	The unique identifier for the CSAR	path	string
start	The index of the first log entry you want (0 returns the whole log)	query	integer (int64)

application/hal+json

200 OK: The operation was executed successfully

LogResponse
400 Bad Request: The given start value is less than zero

RestErrorResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no CSAR for the given identifier

RestErrorResponse

List all supported Platforms

GET /api/platforms

Tags: platforms

Returns a HAL resource (_embedded) containing all Platforms supported by this transformer

application/hal+json

200 OK: OK

PlatformResources
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: Not Found

Get the Details for a specific Platform

GET /api/platforms/{id}

Tags: platforms

Returns the resource object for one specific plugin (platform)


id	The Platform identifier	path	string

application/hal+json

200 OK: The request has been executed with no error!

PlatformResponse
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: There is no platform with the given name

RestErrorResponse

Hypermedia endpoint to get all supported Status operations

GET /api/status

Tags: hypermedia

Status operations are based on Spring Boot Actuator

application/hal+json

200 OK: OK

ResourceSupport
401 Unauthorized: Unauthorized
403 Forbidden: Forbidden
404 Not Found: Not Found

Schema definitions

CsarContainer: object

csar: object[]: The list of csars stored on this system

CsarResponse

CsarResources: object

_embedded: CsarContainer

CsarResponse: object

name: string

This value represents the name (Identifier) of this CSAR

"test"

phases: object[]

The lifecycle phases of this CSAR

LifecyclePhase

GetInputsResponse: object

inputs: object[]: The list of properties associated with this transformation, if this list is empty, the transformation doesn't have any properties to set.

InputWrap

GetOutputsResponse: object

outputs: object[]: The list of outputs associated with this transformation, if this list is empty, the transformation doesn't have any outputs.

OutputWrap

InputsResponse: object

_links: object[]: Link
inputs: object[]: The list of properties associated with this transformation, if this list is empty, the transformation doesn't have any properties to set.

InputWrap

InputWrap: object

default_value: string

the default value of the property

description: string

The description that should be displayed on the Frontend to describe the key

"The URL to the docker registry"

key: string

the unique key for a property

"docker_registry"

required: boolean

Determines if the property is required to start the transformation

true

type: string , x ∈ { name , text , secret , integer , unsigned_integer , float , boolean , invalid_key }

The 'Datatype' of a property. Supported Types are 'name', 'text', 'boolean', 'integer', 'unsigned_integer', 'float' and 'secret'. If you try to set a value of a non existant key. The type in the response will be 'invalid' however this type only occurs in that case

"text"

valid: boolean

true if the property is valid, false otherwise. The server will ignore this value, as it is designed to be read-only.

value: string

gcr.io

LifecyclePhase: object

name: string

the name of this execution phase

"deploy"

state: string , x ∈ { PENDING , SKIPPING , EXECUTING , DONE , SKIPPED , FAILED }

the current state of the phase. Must be one of { PENDING, SKIPPING, EXECUTING, SKIPPED, DONE, ERROR }

"PENDING"

Link: object

href: string
rel: string
templated: boolean

LogEntry: object

context: string

The log context

"org.foo.Bar"

index: integer (int64)

the index of the logline in the list of all loglines for this list of log entries

level: string

The log level for this log entry. The value has to be one of the following: "DEBUG","INFO","WARN","TRACE", "ERROR" or "ALL"

"DEBUG"

message: string

The log message

"Some log message"

timestamp: integer (int64)

The unix timestamp (in milliseconds) when this log was created

1509907624000

LogResponse: object

end: integer (int64): The End index of the logfile at the time of requesting this information.
logs: object[]: The sorted list (ascending by timestamp) of all the logs between start index and the current end index

LogEntry
start: integer (int64): The requested start index

OutputWrap: object

description: string

The description that should be displayed on the Frontend to describe the key

"The URL to the docker registry"

key: string

the unique key for a property

"docker_registry"

type: string , x ∈ { name , text , secret , integer , unsigned_integer , float , boolean , invalid_key }

"text"

value: string

gcr.io

PlatformResources: object

_embedded: PlatformsContainer

PlatformResponse: object

id: string

The identifier for this platform (plugin)

"kubernetes"

name: string

The name for this platform (plugin)

"Kubernetes"

supportsDeployment: boolean

This value is true if a plugin supports in app deployment.

true

PlatformsContainer: object

platform: object[]: The list of platforms supported by this system

PlatformResponse

ResourceSupport: object

_links: object[]: Link

Resources«CsarResponse»: object

_embedded: object[]: CsarResponse
_links: object[]: Link

Resources«PlatformResponse»: object

_embedded: object[]: PlatformResponse
_links: object[]: Link

Resources«TransformationResponse»: object

_embedded: object[]: TransformationResponse
_links: object[]: Link

ResponseEntity: object

body: object
statusCode: string , x ∈ { 100 , 101 , 102 , 103 , 200 , 201 , 202 , 203 , 204 , 205 , 206 , 207 , 208 , 226 , 300 , 301 , 302 , 303 , 304 , 305 , 307 , 308 , 400 , 401 , 402 , 403 , 404 , 405 , 406 , 407 , 408 , 409 , 410 , 411 , 412 , 413 , 414 , 415 , 416 , 417 , 418 , 419 , 420 , 421 , 422 , 423 , 424 , 426 , 428 , 429 , 431 , 451 , 500 , 501 , 502 , 503 , 504 , 505 , 506 , 507 , 508 , 509 , 510 , 511 }
statusCodeValue: integer (int32)

RestErrorResponse: object

error: string

Text description of the HTTP Error

"Not Found"

exception: string

The java class name of the exception that occurred on the server while performing the parsing operation.

"java.io.FileNotFoundException"

message: string

The message of the exception

"File was not found"

path: string

The HTTP Path that was called and caused the exception.

"/files/test.txt"

status: integer (int32)

The HTTP Status code of the exception

timestamp: integer (int64)

The Unix timestamp (in milliseconds) when this exception has occrued (Was constructed internally)

1509907624000

TransformationResources: object

_embedded: TransformationsContainer

TransformationResponse: object

phases: object[]

The phases of the transformation

LifecyclePhase

platform: string

The platform identifier for this transformation

"kubernetes"

state: string , x ∈ { READY , INPUT_REQUIRED , TRANSFORMING , DONE , ERROR }

The Current State of the transformation. Has to be one of the following: "READY", "INPUT_REQUIRED", "TRANSFORMING", "DONE" or "ERROR"

"READY"

TransformationsContainer: object

transformation: object[]: The list of transformations for a csar

TransformationResponse