SHARE THIS ARTICLE

Endpoints

APIs consist of one or more Endpoints. Any Endpoint that needs to be included in the generated code must be described in the API either through the import procedure or using the API specification UI.

To start working on endpoints, open API Editor and navigate to Endpoints in the left navigation menu. Further information about the specification UI is presented as follows:

Endpoint Settings

Endpoint settings contains basic information about an Endpoint (e.g. its name and route, etc.) along with some advanced settings.

Endpoint Settings

The details for each of the fields is listed below:

Name

This is the name of the Endpoint. It is a unique identifier of the underlying resource being accessed.

Group

This is the name of the Endpoint group. It is used to collate similar Endpoints together.

Description

This is the general description of the Endpoint e.g. comments, notes or remarks about this Endpoint.

Method

This is the HTTP Verb for the Endpoint access e.g. { GET, POST, PUT, PATCH, DELETE }

Route

This is the route of the Endpoint. It is the URL segment to be appended to the Base URL for accessing the resource.

Response Type

This represents the response type of the Endpoint, which can be a primitive or a complex type. Please visit Field Types documentation for more details

DateTime Format

This field becomes visible when the Response Type is chosen to be DateTime. 3 formats for DateTime are allowed:

  • Rfc1123
  • Rfc3339
  • Unix TimeStamp

For more details about each format, check out the documentation about Field Types

Server

This option represents the default server that you want to use for the endpoint. This means that this specific endpoint will send requests to the URL specified with this server. You can see Server Configuration documentation for getting more details.

Advanced Settings

Advanced Settings

Advanced settings contain optional flags that are used to customize the generated code.

FlagDescription
Skip authentication?Indicates whether this Endpoint requires authentication. When set, the HTTP requests made to this endpoint do not contain any authentication information.
Allow dynamic form fields?Indicates whether there are any additional optional form fields that are not described here. This option can be used when the optional form fields are far too many to be described in UI. As a result, a dictionary of key value pairs is accepted for loading form fields.

Warning   This flag is not valid for Endpoints where the HTTP Method is GET.

Allow dynamic query params? Indicates whether there are any additional optional query parameters that are not described here. This option can be used when the optional query parameters are far too many to be described in UI. As a result, a dictionary of key value pairs is accepted for loading query parameters.
Collect params?If enabled, then, instead of being treated separately, the endpoint parameters will be collected into a single map of key value pairs
Is response an array?This flag is used to indicate if the Endpoint response is a collection or an array. This array can be of primitive type e.g. String or a complex type Model.

Warning   This flag is not valid for Void Response type

Is this a streaming endpoint?A streaming endpoint needs an open connection to continuously stream the response. When this flag is enabled, the endpoint is considered a streaming endpoint.

Warning   This flag is only valid for Dynamic Response type

Parameters

Parameters section contains definition of request parameters (if any) for the Endpoint. A parameter may be of a primitive type or a complex type as expected by API provider.

Parameters

Name

This is the name of the parameter as expected by the API provider with the request. The spellings and case of alphabets must match with the API.

Description

This is the description of the parameter e.g., comments or notes. This will be emitted as code comments in the generated code.

Default Value

This is the default value of the parameter. This value is used when the parameter is declared as a constant. The format of the value must match the type of the parameter e.g., a Boolean parameter must have either True or False as the default value.

Type

This is the type of the parameter, which can be a primitive or a complex type.

Please visit Field Types for more details on the available types.

Format

This is the format of the parameter, which indicates the mechanism of its submission.

More details on this under Parameter Format below

FlagDescription
Is Optional?This flag indicates whether the parameter is optional. Appropriate handling for such parameter is required for code generation e.g., creating a dictionary to contain of all optional parameter name value pairs. Optional parameters are left out of request if their value is not given. However, if a default value is specified it will be used instead.
Is Array?This flag indicates whether the parameter is an array or a collection. Appropriate handling for such parameter is required for code generation e.g. serialization if necessary.
Is Constant?This flag indicates whether the parameter is a constant value. A constant parameter can be used to transmit value with API calls which may not be altered by the SDK user. In such cases, the default value of the constant parameter is used in the request without generating corresponding method parameters variables.

Warning   This flag is compatible only with primitive type parameters.

Parameter Format

Query

The parameter is submitted as a query parameter e.g. ...?param1=value1

Template

The parameter is substituted in the endpoint route e.g. .../{param1}/items

Form

The parameter is submitted as form field.

Warning   This option is incompatible with GET HTTP Method.

Body

The parameter will be sent as a JSON serialized request body.

Warning   This option is incompatible with GET HTTP Method.

The parameter will be submitted as a header value with the request.

Error Response Codes

List any other possible HTTP Response Codes (other than 200) that your Endpoint might return here. This means that you can provide your own custom description of the error to the user, rather than just the standard HTTP error.

Error Response Codes

The fields are described below:

Error Code

This is the HTTP Error code of the error.

Error Message

This is a description of what the error code means and any other information that should be passed to the user in any instance where this error code occurs.

Exception Class

This is the class of the exception thrown. The dropdown allows you to select any of the models defined as the Exception type in your API description. All properties of the exception class are populated by matching properties from the JSON response received from the API server.

Import CURL

You can also use CURL command to import your endpoint from any server.

Import CURL

Name

This will be set as the name of the Endpoint after the endpoint has been successfully imported

Group

This will be set as the name of the group where the Endpoint will be grouped (related endpoints are group together)

CURL Command

You can write in the CURL command for import in this field. An example is this: curl -X GET -d param1=value1 -G http://your-api-here.com

Options

OptionDescription
Automatically fetch Response Model?If this item is selected then we will automatically execute the CURL Command to observe the response and attempt to generate models for it.

Have questions? Submit a request.