Operations
Create operations
After you created a path you can create one or more operation(s) by clicking on the corresponding capability (POST, GET, PUT, DELETE).
Operations are defined using the following master data:
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 (required)
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 (optional)
Summary: This is a short description of the operation (optional)
Description: This is used to give a more elaborate description of the operation (optional)
Edit operations
You can edit an operation by clicking on the Info icon on the operation's instance page to open the Details view 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's instance page and using the Delete capability.
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 to an operation in the Parameters section by using the Add capability. This can be either an inline parameter or a referenced parameter. When choosing Add inline parameter a new parameter will be created from scratch with referring to an existing or new, reusable schema. If you choose to Add referenced parameter you can select an existing parameter from the list.
Inline parameters
Inline parameters are defined using the following master data:
Name: This is the name of the parameter. The name of a path parameter must be identical to the parameter defined in the path (required)
Location: This flag shows whether the parameter is located in the path, the query or the header of a request ( required)
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 (required)
Required: This is a Boolean. If it is checked, then the property is required, otherwise it is optional (optional)
Title: The title of the parameter (optional)
Format: There you can select a pre-defined string format (optional)
Pattern: The pattern is used for validation within any modifying action by defining a regular expression ( optional)
Minimum Length: Set the minimum length the string must have (optional)
Maximum Length: Set the maximum length the string must have (optional)
Description: A brief overview on what this parameter should represent (optional)
Enumeration Elements: You can specify a list of valid values for the parameter (optional)
Referenced parameters
Referenced parameters are a list of all parameters that have already been created and are visible on the Parameters tab. You can choose one or more and add them to a specific operation.
Managing request bodies of operations
It is possible to add a request body on the operation's instance page in the Request Body section by using the Add capability. You can either Add inline request body or Add referenced request body.
Inline request bodies
An inline request body is defined by using the following master data:
Required: This is a Boolean. If it is checked then the property is required, otherwise it is optional (optional)
Content-Type: There is only one type of content representation: application/json (required)
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 (required)
Description: This is used to give a longer description of the request body (optional)
Referenced request bodies
Referenced request bodies are a list of all the request bodies that have already been created and are visible on the Request Bodies tab. 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 the operation's instance page in the Responses section by using the Add capability. Similar to the Request Body you can either choose to Add inline response or Add referenced response.
Inline responses
Inline responses are defined by using the following master data:
An inline response is defined by using the following master data:
Required: This is a Boolean. If it is checked then the property is required, otherwise it is optional (optional)
Content-Type: There is only one type of content representation: application/json (required)
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 (required)
Description: This is used to give a longer description of the response (optional)
Referenced responses
Referenced responses are a list of all the responses that have already been created and are visible on the Responses tab. 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).