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 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:
NameThis is the name of the Endpoint. It is a unique identifier of the underlying resource being accessed.
GroupThis is the name of the Endpoint group. It is used to collate similar Endpoints together.
DescriptionThis is the general description of the Endpoint e.g. comments, notes or remarks about this Endpoint.
This is the HTTP Verb for the Endpoint access e.g.
RouteThis is the route of the Endpoint. It is the URL segment to be appended to the Base URL for accessing the resource.
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.
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.
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 contain optional flags that are used to customize the generated code.
|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 |
|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 |
|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. |
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.
|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.|
NameThis 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.
DescriptionThis is the description of the parameter e.g. comments or notes. This will be emitted as code comments in the generated code.
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
false as the default value.
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.
This is the format of the parameter, which indicates the mechanism of its submission.
Following are the available formats:
QueryThe parameter is submitted as a query parameter e.g.
TemplateThe parameter is substituted in the endpoint route e.g.
The parameter is submitted as form field.
This option is incompatible with
GET HTTP Method.
The parameter will be sent as a JSON serialized request body.
This option is incompatible with
GET HTTP Method.
HeaderThe parameter will be submitted as a header value with the request.
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
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 CodeThis is the HTTP Error code of the error.
Error MessageThis 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.
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.
You can also use CURL command to import your endpoint from any server.
NameThis will be set as the name of the Endpoint after the endpoint has been successfully imported.
GroupThis will be set as the name of the group in which the Endpoint will be grouped (related endpoints are grouped together).
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
|Automatically fetch Response Model?||If true, we will automatically execute the CURL Command to observe the response and attempt to generate models for it.|