Version

    Endpoint Configuration

    Contains configuration of the REST endpoint: job name, URL, HTTP methods that this endpoint will respond to, and a category.

    When connected to a Server sandbox, the Endpoint Configuration shows the current status of service deployment. The service will respond to incoming requests only when it is in the published state.

    Data Service jobs can be published directly from Designer if connected to a Server sandbox.

    Designer will attempt to redeploy the service whenever the job or the endpoint configuration is changed. The redeployment happens when you save changes in the job; however, the deployment may fail if the configuration is invalid.

    Due to potential failures, the automatic redeployment of the service is useful mostly during development, when changes to the jobs are frequent and you want to quickly test the service behavior. In production environment, it is recommended to upload the service .rjob files to the Server sandbox and deploy the service using CloverDX Server management console instead. This way, you can make sure it has been deployed correctly.

    data service 3210
    Figure 316. Main .rjob editor
    Endpoint configuration

    Endpoint name

    Title of a job. It should be a human-readable title. Displayed in a documentation and user interface.

    Endpoint URL

    A URL of a REST job endpoint where it listens for connections. The grayed part cannot be changed. It is automatically derived from a CloverDX Server URL and (optionally) sandbox specific prefix. The prefix can be defined by a sandbox level property "data_service_base_path". See Execution properties for its description and usage.

    The URL may contain a specification of path parameters using a {param_name} syntax.

    Since version 5.1 you can use regular expressions for matching path parameters in URLs, for example: use {param_name:.+}(e.g. {filename:.+}) for the parameter to accept any character.

    Note: unless you use the regular expression above, parameters are not matched if the value contains / (slash).

    Request method

    The list of HTTP methods this endpoint will respond to.

    If client uses an HTTP method unsupported by the endpoint, they receive a response code: 404 - Not found.

    Category

    The category is used in the Data Apps catalog to group related services. Only published services with the Data App feature enabled are visible in the catalog.

    Icon

    The image referenced by this optional parameter is used in Data Apps catalog for better orientation in the list of all available Data Apps.

     

    Input

    Specification of request body format.

    Format

    Expected format of request body. Binary, String or JSON.

    JSON is the default for newly created REST jobs since 5.12.

    "Binary" streams the request body in chunks for further processing with an arbitrary reader component.

    "String" returns the whole request body as a single string.

    "JSON" parses the request body as a JSON document into a variant data field for further processing with CTL functions.

    Specification of input HTTP parameters.

    Name

    Name of the parameter

    Location

    Path parameter or Query parameter

    Type

    The type of data accepted by this parameter. Type conversion happens automatically if there is an edge connected to the Parameters output port of the Rest Job Input component. See Input and Output components.

    Required

    Data Service job automatically validates the presence of required parameters. If any of the required parameters are missing, the result is Invalid request.

    Label

    The label used in Data App form.

    Description

    Human-readable description of the parameter. Will be displayed in a service documentation.

    Sensitive

    Marking the parameter sensitive will cause the value of the parameter to be redacted from logs.

    Value Hint

    Placeholder text used in the Data App form.

    Default Value

    Default value of the parameter. It is not used if parameter is marked as required.

    Values

    The specific property for the enumeration parameter.

    Defines static values of the parameter.

    Dynamic Values

    The specific property for the enumeration parameter.

    The endpoint of a Data Service from which the values will be obtained in Data App form. The obtained values will overwrite the ones from the Values property. The endpoint must support the GET method and it must be hosted on the same server as the Data App. If the sandbox is connected to the server, a list of published Data Services is offered. The response of the endpoint must be a JSON.

    The example of two possible JSON formats:

    [
    {
        "value": "v1",
        "label": "Label 1"
    },
    {
        "value": "v2",
        "hint": ""
    }
]

    or

    {
    "customMetadataName": [
        {
            "value": "v1",
            "label": "Label 1"
        },
        {
            "value": "v2",
            "hint": ""
        },
        {
            "value": "v3",
            "label": "Label 3",
            "hint": ""
        }
    ]
}

    The value field is required, label is optional, other fields are skipped.

    The endpoints with SSL configuration should be defined this way: {HTTPS_connector_name}:/{endpoint}.

    An example of endpoint with SSL configuration: httpsConnector:/data_service_endpoint.
    An example of endpoint without SSL configuration: /data_service_endpoint.

     

    Output

    Specification of a response format and HTTP status codes. See the Generating response content section for more details about the output.

    Format

    One of data formats for automatic serialization (JSON, XML, CSV), “Custom” for Custom Serialization or "File" for Using Static File as Response.

    JSON-specific settings

    Additional settings for JSON payloads, affecting the formatting; can be used to simplify the parsing of the response on the consumer side for typical payloads:

    Do not write metadata name causes the JSON formatter to omit the top-level object and only send an anonymous array instead. Use this option when your REST response contains only one type of record (metadata), i.e. when you connected edge to only single port on the response component.

    Do not write top level array omits the top-level array and generates only a single object. Enable this option for services that return only single output record. The graph will fail, if the option is enabled and multiple output records arrive.

    Both options simplify the output and make it easier to parse.

    Default Response

    HTTP status code and reason phrase. Success is returned after the job finishes, Invalid Request is returned in the case of a missing required parameter, Error is returned in the case of any other failure.

    Default success status code is 200. It is recommended to use more specific status codes based on the functionality of your job. For example 201 - Created, 202 - Accepted or 204 - No content.

    Error responses are described in section Exceptions and Error Handling.

    Note: Using the setResponseStatus CTL function in any of the job’s components overrides the default response status code with a code specified in the function.

    Response example

    Displayed after clicking on the link “Show response example”.

    Shows an artificial example response and how it is affected when additional JSON formatting options are enabled.

     

    Documentation

    Documentation elements do not have any effect on the job functionality. Description and Example endpoint output are included in the generated service documentation to help consumers use your REST endpoint.

    Example endpoint output is currently just a placeholder and is not reflected in the service documentation.