Endpoints Essentials

This article is outdated. Please click here to see the newer version.

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. Further information about the specification UI is presented as follows.

Endpoint Settings

Endpoint settings contain the basic information about an Endpoint i.e., its name and route.

Element

Description

Name Name of the Endpoint. This is a unique identifier of the underlying resource being accessed.
Group Name of the Endpoint group. This is used to collate similar Endpoints together.
Description General description of the Endpoint e.g., comments, notes or remarks about this Endpoint.
Method HTTP Verb for the Endpoint access e.g. { GET, POST, PUT, PATCH, DELETE }
Route Route of the Endpoint. This is the Url segment to be appended to the Base Url for accessing the resource.

Response Settings

Response settings are used to describe the response of an API request for an Endpoint. APIMATIC supports both the cases where an Endpoint response is a primitive type or a complex type.

Element

Description

Type This represents the response type of the Endpoint, which can be a primite or a complex type.
String String type, e.g. string, NSString*
Binary Binary data, e.g. stream, NSData*
Boolean Boolean type, e.g. bool, BOOL
Number Integer type, e.g. int, Integer
Precision Numerical precision, e.g. double
DateTime Date and Time type, e.g. Datetime
Complex Types All complex types described in the API are listed here. The response will be deserialised into this model when the endpoint is called.
Is response an Array? This flag is used to indicate if the response is a collection or an array. This array can be of primitive type e.g., String or a complex type Model.

Parameters

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

Element

Description

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.
String String type e.g., string, NSString*
Boolean Boolean type e.g., bool, BOOL
Number Integer type e.g., int, Integer
Precision Numerical precision e.g., double
File A file to be uploaded
Complex Types All complex types described in the API are listed here
Format This is the format of the parameter, which indicates the mechanism of its submission.
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 a form field.
Note: This option is incompatible with GET HTTP Method.
Body The parameter will be sent as a Json serialized request body.
Note: This option is incompatible with GET HTTP Method.
Header The parameter will be submitted as a header value with the request.
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.
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.
Note: This flag is compatible only with primitive type parameters.

 

Have more questions? Submit a request

Comments