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.
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 contain optional flags that are used to customize the generated code.
| Flag | Description |
|---|---|
| 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 |
| 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 |
| 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 |
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.
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| Flag | Description |
|---|---|
| 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.
Header
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.
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.
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.comOptions
| Option | Description |
|---|---|
| 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.