Import API Proxy (With Override)

Overview

Imports an API Proxy from a ZIP file. If an API Proxy with the same name already exists, it will be overridden. If it does not exist, a new API Proxy will be created. This endpoint supports optional metadata for deployment and routing configuration.

Endpoint

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/import/

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header Value Required
Authorization Bearer {token} Yes
Content-Type multipart/form-data Yes

Path Parameters

Parameter Type Required Description
projectName string Yes Project name where the API Proxy will be imported
apiProxyName string Yes API Proxy name (will override existing API Proxy with this name)

Form Data

Parameter Type Required Description
metadata string (JSON) Yes Metadata for API Proxy creation/update. See Metadata Object
apiProxyExportFile file Yes ZIP file containing the API Proxy export. Must have .zip extension

Metadata Object

The metadata parameter is a JSON string containing optional configuration for the import process.

Full JSON Metadata Example - Basic Import

{
  "deploy": false,
  "deployTargetEnvironmentNameList": null,
  "routing": null,
  "maintenanceMode": null
}

Full JSON Metadata Example - Import with Deployment

{
  "deploy": true,
  "deployTargetEnvironmentNameList": ["production", "staging"],
  "routing": null,
  "maintenanceMode": null
}

Full JSON Metadata Example - Import with Routing

{
  "deploy": false,
  "deployTargetEnvironmentNameList": null,
  "routing": {
    "algorithm": "ROUND_ROBIN",
    "addressList": [
      {
        "address": "https://backend1.example.com",
        "weight": 1,
        "soapType": null
      },
      {
        "address": "https://backend2.example.com",
        "weight": 1,
        "soapType": null
      }
    ]
  },
  "maintenanceMode": false
}

Metadata Object Fields

Field Type Required Default Description
deploy boolean No false Deploy API Proxy after import
deployTargetEnvironmentNameList array[string] No null List of environment names to deploy to (if deploy=true)
routing object No null Routing configuration. See Routing Object
maintenanceMode boolean No null Enable/disable maintenance mode

Routing Object

Field Type Required Description
algorithm string No Routing algorithm. See EnumRoutingAlgorithm
addressList array[object] No List of routing addresses. See Routing Address Object

EnumRoutingAlgorithm (routing.algorithm)

  • ROUND_ROBIN - Round-robin load balancing
  • WEIGHTED_ROUND_ROBIN - Weighted round-robin load balancing
  • LEAST_CONNECTIONS - Least connections load balancing
  • RANDOM - Random selection
  • IP_HASH - IP hash-based routing
  • URL_HASH - URL hash-based routing

Routing Address Object

Field Type Required Description
address string Yes Backend address URL
weight integer No Weight for weighted algorithms (default: 1)
soapType string No SOAP version for SOAP APIs. See EnumSoapApiPortType

EnumSoapApiPortType (soapType)

  • SOAP11 - SOAP 1.1
  • SOAP12 - SOAP 1.2

Notes

  • File must be a valid ZIP archive
  • File must end with .zip extension (case-insensitive)
  • ZIP file must contain a valid API Proxy export JSON file
  • If deploy=true, requires ROLE_DEPLOY_UNDEPLOY_PROXIES permission
  • Routing configuration is optional and can be set later
  • Maintenance mode can be enabled/disabled during import

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true,
    "message": "Deployment completed successfully",
    "environmentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployed successfully"
      }
    ]
  }
}

Response Fields

Field Type Description
status string Response status: SUCCESS or FAILURE
deploymentResult object Deployment result (if deploy=true). See Deployment Result Object

Deployment Result Object

Field Type Description
success boolean Overall deployment success status
message string Deployment message
environmentResults array[object] Results per environment

Environment Result Object

Field Type Description
environmentName string Environment name
success boolean Deployment success status for this environment
message string Deployment message for this environment

Success Response (200 OK) - Without Deployment

{
  "status": "SUCCESS"
}

Error Response (400 Bad Request)

{
  "error": "bad_request",
  "error_description": "projectName value can not be empty!"
}

or

{
  "error": "bad_request",
  "error_description": "apiProxyName value can not be empty!"
}

or

{
  "error": "bad_request",
  "error_description": "apiProxyExportFile parameter can not be empty!"
}

or

{
  "error": "bad_request",
  "error_description": "apiProxyExportFile parameter must be in zip file format and must end with zip extension!"
}

Common Causes

  • Empty projectName or apiProxyName
  • Empty or missing file
  • File is not a ZIP archive
  • File does not have .zip extension
  • Invalid API Proxy export format
  • Invalid metadata JSON format
  • Deployment failed (if deploy=true)

Error Response (401 Unauthorized)

{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}

Error Response (404 Not Found)

{
  "error": "not_found",
  "error_description": "Project(MyProject) was not found or user does not have privilege to access it!"
}

cURL Example

Example 1: Basic Import (No Override)

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "metadata={\"deploy\":false}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 2: Import with Deployment

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "metadata={\"deploy\":true,\"deployTargetEnvironmentNameList\":[\"production\",\"staging\"]}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 3: Import with Routing Configuration

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'metadata={"deploy":false,"routing":{"algorithm":"ROUND_ROBIN","addressList":[{"address":"https://backend1.example.com","weight":1},{"address":"https://backend2.example.com","weight":1}]}}' \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 4: Import with Full Configuration

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'metadata={"deploy":true,"deployTargetEnvironmentNameList":["production"],"routing":{"algorithm":"WEIGHTED_ROUND_ROBIN","addressList":[{"address":"https://backend1.example.com","weight":3},{"address":"https://backend2.example.com","weight":1}]},"maintenanceMode":false}' \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Notes and Warnings

  • Override Behavior:
    • This endpoint overrides existing API Proxies with the same name
    • Existing API Proxy configuration will be replaced
    • Original API Proxy data is lost after override
  • Deployment:
    • If deploy=true, API Proxy will be deployed after import
    • Requires ROLE_DEPLOY_UNDEPLOY_PROXIES permission
    • Deployment targets must be specified in deployTargetEnvironmentNameList
    • Deployment results are returned in the response
  • Routing Configuration:
    • Routing can be configured during import
    • Routing algorithm and addresses can be set
    • Routing configuration is optional
  • Maintenance Mode:
    • Maintenance mode can be enabled/disabled during import
    • Useful for importing API Proxies in maintenance state
  • File Format:
    • File must be a valid ZIP archive
    • File must end with .zip extension (case-insensitive)
    • ZIP file must contain valid API Proxy export JSON
  • Metadata Format:
    • Metadata must be valid JSON
    • Metadata is passed as a form field (string)
    • All metadata fields are optional
  • Project Validation:
    • Project must exist
    • User must have access to the project
    • User must have ROLE_MANAGE_PROXIES permission
  • Import Content:
    • Import includes all API Proxy configurations
    • Includes all associated policies
    • Includes routing, cache, CORS, and other settings
  • Permissions:
    • Requires ROLE_MANAGE_PROXIES permission
    • Requires ROLE_DEPLOY_UNDEPLOY_PROXIES permission if deploy=true
    • User must have access to the target project
  • File Size:
    • Large export files may take longer to import
    • Ensure sufficient network bandwidth and server resources
  • Validation:
    • Import validates API Proxy structure
    • Invalid configurations may cause import to fail
    • Check error messages for validation issues
  • Deployment Results:
    • Deployment results are included in the response
    • Check deploymentResult for deployment status
    • Each environment deployment result is included separately