Mock Servers

Mock servers facilitate API interaction in development, integration, and testing scenarios. They simulate API behavior by returning predefined responses based on the API's OpenAPI specification, enabling development and testing without relying on a live backend.

Key use cases

• Development staging
  Simulate API responses before backend implementation is complete, allowing frontend work to progress independently.

• Credential-free testing
  Test integrations without needing actual authentication credentials, simplifying the testing process.

• Production data protection
  Create a safe testing environment that prevents accidental modifications to live data systems.

• Consistent test environment
  Generate reliable, predictable API responses that remain consistent across multiple test runs.

Example

For a partner integrating the Retarus Fax API into a customer’s application, thorough testing and preparation are critical before transitioning to production. Below is an approach to ensure a seamless integration:

1. Use the provided API Explorer to simulate API interactions without affecting live systems.

2. Identify required parameters (e.g., recipient numbers, document URLs) and headers.

3. Send API requests to Retarus' mock server, which mimics production behavior.

4. Ensure the application correctly parses responses, such as extracting jobId from success responses or logging error details (error code, messages).

Once integration testing is complete, the partner can update the API URL from the mock server to the live Retarus API.

Mock server limitations

While mock servers provide valuable tools for API testing and exploration, they operate with several inherent limitations that you need to understand.

• Authentication simulation
  Mock servers do not validate or enforce authentication mechanisms. API keys, OAuth tokens, and other credentials are accepted but not verified.
• Response generation
  Mock servers generate sample responses based on the OpenAPI description without executing any business logic.
• Error simulation
  The mock server simulates only failures that are documented as possible error responses (400, 401, 500, etc.) in the OpenAPI definition.
• Data processing
  No data is stored or modified regardless of the HTTP method used. POST, PUT, and DELETE operations appear successful but don't affect any backend systems.

API Explorer

To interact with Retarus APIs without affecting live systems, use mock servers in the API Knowledge Center. The built-in API Explorer serves as an interactive client, allowing you to send requests to these servers and validate responses.

1. Navigate to the API endpoint you want to test (e.g.,Cloud Fax - Sending Fax API - Fetching the status report for a single job).

2. Click the Try it button in the right sidebar.

   

3. The API Explorer opens with two main panes:

   • Request (left): Contains all elements needed to make an API request.
   • History/Environment (right): Shows request history and environment settings.

   

   Note: You can click the request link at the top of the pane to open reference documentation in another tab. To close the API Explorer, use the X icon at the top left.

Configuring the request

Path parameter variables

• If the endpoint includes path parameters, they appear as variables in the URL.
• Red-highlighted variables indicate required values that must be entered before sending the request.

Parameter tabs

Below the endpoint, you can configure different aspects of your request:

• Security
  Enter API keys, Basic Auth credentials, or other authentication details.
• Body
  Provide request body data in JSON format (for POST, PUT, or PATCH requests).
• Query
  Enter query parameters such as filters, dates, or pagination settings.
• Headers
  Set custom HTTP headers for the request.
• Cookies
  Add cookies, if applicable.

Choosing an example

If the OpenAPI definition includes examples, you can select one when using the mock server. This automatically populates some fields with sample data, so you only need to fill in the remaining fields.

Sending the request

1. Ensure that Mock server is displayed in the Environment dropdown of the Request pane.

   

2. Select the appropriate request method (GET, POST, PUT, etc.) from the dropdown next to the endpoint.

   

3. Configure any required parameters. For example, to set path parameters (like customer number and job ID):

   • Click on the parameter (e.g., {{custNr}}) to open the Undefined variable value dialog.
   • Click Set value to open the Edit variable dialog.
   • Enter your desired value in the Value field.
   • Click Save.

   

   • Repeat these steps for any other required path parameters.

   Note: The mock server does not validate credentials or input values for correctness.

4. Click the Send button to submit your request to the mock server.

   • The mock server returns a response based on the OpenAPI definition.

5. Review the returned response, which includes:

   • Status code
   • Headers
   • Response body

   

Sending requests with an external API client

You can use the API Explorer to generate API requests and copy them for use in external tools such as Postman, curl, or your own applications. This allows for seamless testing outside the Retarus API Knowledge Center.

1. Configure your request in the API Explorer as described earlier (set headers, parameters, etc.).
2. Click the Preview button.
   → The endpoint URL is displayed next to the selected method.

3. Click the copy button (next to Preview) to copy the complete request.
4. Use your preferred API client to send the request.

Example - sending the request with Postman

1. Open Postman.

2. Choose the desired HTTP method (e.g., GET) and paste the copied request URL.

   

3. Ensure the correct authentication method (as defined in the OpenAPI definition) is selected, for example:

   

   Note: Mock servers don't perform actual authentication, so you can leave fields empty or enter any values. required authentication headers (e.g., Authorization: Basic Base64Encoded(username:password)) must still be included.

   If you don't provide the Authorization header, the server will return a 401 Unauthorized error:

   {
       "code": 401,
       "message": "Not authenticated. Supported authentication types: httpBasicAuth."
   }

4. Click Send.

Sending requests with cURL

1. Navigate to the desired API endpoint.

2. In the right sidebar, ensure the mock server is selected as the server to send requests to (it contains _mock in the URL).

   

3. Select curl at the top right of the sidebar.

   

4. Copy the displayed curl command.

5. Execute the copied command in your terminal or command-line environment.

Sending requests with Python

1. Navigate to the desired API endpoint.

2. In the right sidebar, ensure the Mock server is selected as the server to send requests to (it contains _mock in the URL).

3. Select Python at the top right of the sidebar.

   

4. Copy the generated Python code snippet and integrate it into your application.

Example Python implementation

Below is an example of a simple Python script that integrates with the Retarus Cloud Fax API:

import requests

def send_fax(cust_nr, username, password):
    # Build the API URL using the customer number.
    url = f"https://developers.retarus.com/_mock/fax/fax4a-api/{cust_nr}/fax"
    
    # Define the payload for the POST request.
    payload = {
        "recipients": [
            {
                "number": "+498900000000",
                "properties": [
                    {"key": "FromName", "value": "John Doe"},
                    {"key": "FromCompanyName", "value": "Retarus"},
                    {"key": "FromTelNumber", "value": "+49 89 5528-2525"},
                    {"key": "ToName", "value": "Jane Doe"},
                    {"key": "ToCompanyName", "value": "Acme International Ltd."},
                    {"key": "ToFaxNum", "value": "+498900000000"},
                    {"key": "SubjectTitle", "value": "Retarus OpenAPI testfax"},
                    {"key": "SubjectText", "value": "This testfax was sent from Retarus OpenAPI Portal."}
                ]
            }
        ],
        "renderingOptions": {
            "paperFormat": None,
            "coverpageTemplate": "coverpage-default.ftl.html"
        }
    }
    
    # Set the HTTP headers.
    headers = {"Content-Type": "application/json"}
    
    # Send the POST request using HTTP Basic Authentication.
    response = requests.post(url, json=payload, headers=headers, auth=(username, password))
    return response

def main():
    # Define your credentials and customer number.
    # Replace these placeholders with your actual credentials.
    cust_nr = "9991"
    username = "YOUR_httpBasicAuth_username_PARAMETER"
    password = "YOUR_httpBasicAuth_password_PARAMETER"

    print("Sending test fax request to Retarus Fax API...")
    
    # Call the function to send the fax.
    response = send_fax(cust_nr, username, password)
    
    try:
        # Try to parse the response as JSON.
        data = response.json()
    except Exception:
        # Fallback to text if JSON parsing fails.
        data = response.text
    
    print("Response from Retarus Fax API:")
    print(data)

if __name__ == "__main__":
    main()

Save this code to a file (e.g., fax-api-request.py) and run it:

$ python fax-api-request.py
Sending test fax request to the Retarus Fax API mock server...
Response from the Retarus Fax API mock server:
{'jobId': 'FJKQQUVF1J0IADYARQEXKC'}

The received response confirms that the mock server processed your request successfully, returning a jobId as specified in the OpenAPI definition.