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. 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)
Note:

If your project is based on Java Spring Boot Stack 2.0 and the extension Saga Pattern Support is enabled, each operation can be marked as a Saga Participant while creating. When doing this, the header "Long-Running-Action" is automatically added to the operation. This header then gets filled with the lra-Id when executing the API operation during a Saga in order to correlate Saga participants across multiple services.

Edit operations

You can edit the master data of a operation by clicking the Edit operation details button in the Operation Details section on the operation's instance page. The fields that can be edited are Operation Id, Tags, Summary and Description.

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

Note:

For Domain Service Projects of type Java Spring Boot where the extension Saga Pattern Support is enabled the flag Saga Particpant can be edited.

Delete operations

You can delete a operation by clicking the Delete operation button in the upper right corner of the operation instance page.

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

Note:

Not possible for GET and DELETE!

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. Added responses of the operation can be edited or deleted by using the the inline actions Edit or Remove of the table.

Warning:

There must be at least one response for each operation!

Inline responses

An inline response is defined by using the following master data:

  • Status Code: This is a number represents the response status code, should be a valid status code number and unique in the responses list (required)
  • Content-Type: There is only one type of content representation: application/json (optional), and (required) if Schema is defined.
  • 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 (optional), and (required) if Content-Type is defined.
  • Description: This is used to give a longer description of the response (required)

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).