API Operations

Create Operations (POST, GET, PUT, DELETE)

You can create an operation by using the corresponding capability (POST, GET, PUT, DELETE).

Operations are defined using the following master data:


Property	Description
Operation Id	This is the name of the operation. It is unique within an API namespace. The operation ID is case sensitive. Please note, that only the characters A-z (without special characters), digits and the special characters "_" and "-" are allowed for naming operations! The operation ID cannot be changed after creation. It is recommended to follow common naming conventions. This field is mandatory.
Tags	This is used for documentation purposes. It represents the logical grouping of the operations, for example, by resource. An operation can have none or more tags. This field is optional.
Summary	This is a short description of the operation. This field is optional.
Description	This is used to give a more elaborate description of the operation. This field is optional.

Edit Operations

You can edit an operation by using the Information capability on the operation instance page and navigating to the Master Data section. There you can use the Edit Master Data capability to alter the information of the operation. The following information can be edited:

Tags
Summary
Description

Furthermore, it is also possible to set the deprecated flag which will automatically deprecate your operation.

Delete Operations

You can delete an operation by opening the Details view from the operation instance page and clicking on the Delete icon.

You will need to confirm the action before the selected command is permanently deleted.

Managing Parameters of Operations

It is possible to add a parameter from an operation instance in the parameters section by using the Add capability. Inline parameters are created from scratch with referring to an existing or new, reusable schema.

They are defined using the following master data:


Property	Description
Name	This is the name of the parameter. The name of a path parameter must be identical to the parameter defined in the path. This field is mandatory.
Location	This flag shows whether the parameter is located in the path, the query or the header of a request. This field is mandatory.
Schema	This is a list of the primitive schema types that have already been created. The chosen schema will be applied to the parameter that has being created. A new schema can be created while typing in the drop-down and choosing Add. This field is mandatory.
Required	This is a Boolean. If it is checked, then the property is required, otherwise it is optional.
Description	This is used to give a longer description of the error that occurred. This field is optional.

Referenced parameters are a list of all parameters that have already been created and are visible in the parameters overview page. You can choose one or more and add them to a specific operation

Managing Request Bodies of Operations

Not possible for GET and DELETE!

It is possible to add a request body on an operation instance page in the Request Body section by using the Add capability.

An inline request body is defined by using the following master data:


Property	Description
Required	This is a Boolean. If it is checked then the property is required, otherwise it is optional.
Content Type	Mapping of a parameter's representations. There is only one type of content representation: application/json. This field is mandatory.
Schema	A list of all schema types that have already been created. The chosen schema will be applied to the request body that's being created. This field is mandatory.
Description	This is used to give a longer description of the request body. This field is optional.

Referenced request bodies are a list of all the request bodies that have already been created and are visible in the "Request Bodies" overview page. You can choose one referenced request body and add it to a specific operation.

Managing Responses of Operations

It is possible to add a response on an operation instance page in the "Responses" section by using the "Add" capability.

Inline responses are defined by using the following master data:


Property	Description
Status	The status of a response expresses the type of the response (e.g. error, success etc.). The possible values are integers between 100 and 600 (including). This field is mandatory.
Content Type	Mapping of a parameter's representations. There is currently only one type of content representation supported: application/json. This field is mandatory.
Schema	A list of all schema types that have already been created. The chosen schema will be applied to the response that's being created. This field is optional.
Description	This is used to give a longer description of the error that occurred. This field is mandatory.

Referenced responses are a list of all the responses that have already been created and are visible in the "Responses" overview page. You can choose one, assign a status to it and add it to a specific operation.

Edit an Operation's Documentation

The documentation is used to provide further information regarding the implementation of the operation. There are three sections used to organize the documentation: the pre-condition(s), the operation logic/flow and the post-condition(s).