Documentation / API Endpoint / HTTP Request

To call a REST API, the Client Application has to construct an HTTP Request. The http request has to constructed according to the specifications or the API Server will fail to understand Client's request.
When creating a new API Endpoint in Api-On-Cloud's Editor, an important step is to define how the the HTTP Request looks like. 

Api-On-Cloud's API Editor divides the HTTP Request into 4 components:

  1. Headers (optional)
  2. Query Parameter (optional)
  3. Request Body (optional)
  4. Path (required)

Headers, Query Parameters and Request Body are optional. An API Endpoint can be created with or without them.
However, every API Endpoint must have a Path defined

Path

The Path can be defined by entering a value in API Path text field, see an example below

Click here for more information on API Path text field

Headers

Headers for the Request can be defined using the Set HTTP Request Header(s) panel. Defining headers are optional.

The Request Headers panel is divided into 3 sections:

  • Headers Match Type (required - must pick a value from this list)
  • Header Name and Header Value (required - must provide a value for both before pressing the Add Header button)
  • Table displaying Header Name/Value pairs that have added to the HTTP Request definition
Headers Match Type

Pick one of the two options provided in this list. The two options are EXACT and ANY

EXACT: When "exact" is picked then the defined API will expect the request to have exactly the same header value
ANY: When "any" is picked then the defined API will not verify that the header value received from the Client Application is the same value provided in the Editor.

   

If headers match type is EXACT and
Header Name equals token and
Header Value equals somerandontoken
then the http request must have a header named token  and its value must be somerandomtoken. Otherwise, the client application will not receive any response back from the Api-On-Cloud API Server
If headers match type is ANY and
Header Name equals token and
Header Value equals somerandomtoken
then the http request must have a header named token but the value of the header can be anything. The header token can have a value of 1 or abc or somerandomtoken or anyotherrandomstring 

Query Parameters

Query Parameters can be defined using the Set Request Query Parameter(s) panel. Defining query parameter(s) is optional.

The Query Parameters panel is divided into 3 components

  1. Request Parameters Match Type (required - must pick one of the two values from this list if you want to define query parameters
  2. Query Parameter Key and Query Parameter Value (must provide a value for both before pressing the Add Query Parameter button)
  3. Table displaying all query parameter key/value pairs added to the HTTP Request definition
Query Parameters Match Type

Pick one of the two options available in this list. The two options are EXACT and ANY

EXACT: When "exact" is picked then HTTP Requests must have the exact same query parameter Keys and Values
ANY: When "any" is selected then HTTP Requests must have the same query parameter Keys. Values for the parameter keys can be any string such as: abc, xyz, 123, somerandomparametervalue


   

If Query Parameters Match Type equals exact and
Query Parameter Key equals min-price and
Query Parameter Value equals 15
then the HTTP Request must contain a query parameter named min-price and its value must be 15. Otherwise, no response will be received from Api-On-Cloud's API Server
If Query Parameters Match Type equals any and
Query Parameter Key equals min-price and
Query Parameter Value equals 15
then the HTTP Request must contain a query parameter named min-price but its value can be any string such as: 15 or abc or some-other-random string. Otherwise, no response will be received from Api-On-Cloud's API Server

Request Body

A request body can be provided for HTTP Post and HTTP Put requests. To specify the contents of the request body, select the checkbox displayed on the screen 

Additional fields are displayed upon checking the checkbox. Contents of the request body can be specified in the additional fields. The additional fields are:

  • Request Body Content-Type (required)
  • Match Type (required)
  • Request Body (required)
Request Body Content-Type

HTTP Post and HTTP Put APIs with request body cannot be saved without specifying the Content-Type. Some examples of Content-Type are:

  • application/json
  • text/plain
  • text/xml
  • text/html
Match Type

A value must be picked from this list before saving HTTP Post or HTTP Put requests with a body. The two options are exact and any.

  • Exact: When "exact" is picked, the defined API Endpoint expects to receive the exact contents specified in the Request Body. If the API Endpoint doesn't receive the exact same contents then no response will be returned by the API Endpoint.
  • Any: When "any" is picked, the defined API Endpoint will not check and compare the contents of the request body. A response will be returned by the Api-On-Cloud API Server as long as the Calling Application sends a request with a body. The Content-Type.
If Content-Type is application/json and
Match Type is exact and
Request Body contains { "City": "New York", "State": "New York" }
then the Calling Application must have Content-Type header set to application/json and request body must equal { "City": "New York", "State": "New York" }.
No response will be returned by Api-On-Cloud API Server if the json doesn't match
If Content-Type is application/json and
Match Type is any and
Request Body contains { "City": "New York", "State": "New York" }
then the Calling Application must have Content-Type header set to application/json but the request body can contain any valid json, such as:
{ "City": "New York", "State": "New York" }
OR
{ "City": "Los Angeles", "State": "California" }
OR
{ "Name": "John Smith", "identifier": "112233" }