Skip to main content

API 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 and 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.

Example Response​

A sample value of the response that should be valid for the response type specified

For example, for the Precision type response, a valid example can be 2.3. This example is useful for documentation purposes where it can give an indication to the users of what the response will look like.

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 check out our documentation for Server Configuration for 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. 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 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. This flag is only valid for Dynamic Response type.
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. This flag is not valid for Void 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

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. This flag is compatible only with primitive type 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.

Following are the available formats:

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.

caution

This option is incompatible with GET HTTP Method.

Body​

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

caution

This option is incompatible with GET HTTP Method.

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

Example​

A sample value of the parameter useful for documentation to help users get an idea of what the parameter value can look like. This value must be valid for the selected parameter Type e.g. a valid value for parameter of type Precision is 2.5.

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 definition. 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 in which the Endpoint will be grouped (related endpoints are grouped together).

CURL Command​

APIMatic supports importing a curl command as an endpoint. You can write the curl command for import in this field. This is what a curl command looks something like: curl -X GET -d param1=value1 -G http://your-api-here.com

Options​

OptionDescription
Automatically fetch Response Model?If true, we will automatically execute the CURL Command to observe the response and attempt to generate models for it.