Structure

The Ping Proxies API follows RESTful principles with consistent URL patterns, standard HTTP methods, and JSON-formatted requests and responses. This page explains the core structural components of the API.

​

Base URL

All API requests should be made to the following base URL:

https://api.pingproxies.com/1.0/

​

URL Structure

The API URLs follow a consistent pattern:

/[version]/[scope]/[resource]/[action]/[identifier]

​

Components

All Public API therefore follow this URL format:

https://api.pingproxies.com/1.0/public/user/[resource]/[action]/[identifier]

​

Example URLs

/1.0/public/user/proxy/search
/1.0/public/user/proxy/retrieve/{proxy_id}
/1.0/public/user/proxy_user/create
/1.0/public/user/service/edit/{service_id}

​

HTTP Methods

The API uses standard HTTP methods to perform different actions:

​

Method and URL Mapping

The HTTP method and URL structure work together to define the operation:

​

Request Format

​

Headers

All requests should include the following headers:

​

Request Body

For POST and PATCH requests, data should be sent as JSON in the request body:

{
  "proxy_user_id": "example_user",
  "proxy_user_password": "secure_password",
  "proxy_user_metadata": {
    "department": "Marketing",
    "project": "Q2 Campaign"
  }
}

​

Query Parameters

For GET requests, parameters are passed in the URL query string:

/proxy/search?country_id=us&proxy_type=datacenter&page=1&per_page=25

Common query parameters include:

​

Response Format

All API responses are JSON objects with a consistent structure:

{
  "data": {
    // Resource data or array of resources
  },
  "message": "Operation successful message",
  "page": 1,           // Only in paginated responses
  "per_page": 25,      // Only in paginated responses
  "total_count": 157,  // Only in paginated responses
  "item_count": 25     // Only in paginated responses
}

​

Success Responses

Successful responses include:

• HTTP status code in the 200 range
• data field containing the requested resource(s)
• message field with a success message

Example of a successful retrieve operation:

{
  "data": {
    "proxy_id": "abc123",
    "proxy_ip_address": "192.168.1.1",
    "proxy_status": "active"
    // Additional fields...
  },
  "message": "Proxy successfully retrieved."
}

Example of a successful search operation:

{
  "data": [
    {
      "proxy_id": "abc123",
      "proxy_ip_address": "192.168.1.1"
      // Additional fields...
    },
    {
      "proxy_id": "def456",
      "proxy_ip_address": "192.168.1.2"
      // Additional fields...
    }
  ],
  "message": "Proxy search successful.",
  "page": 1,
  "per_page": 25,
  "total_count": 157,
  "item_count": 25
}

​

Error Responses

Error responses include:

• HTTP status code in the 400 or 500 range
• error field with the error type
• message field with a description of the error
• api_request_id field for reference when contacting support

Example error response:

{
  "error": "Bad Request",
  "message": "The proxy_user_id field is required.",
  "api_request_id": "0a5a76aa-e286-477b-b88f-e5b492a0ba70"
}

​

HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of a request:

​

Data Types

The API uses standard JSON data types:

​

Date and Time Format

All date and time values in the API use the format below:

YYYY-MM-DDT hh:mm:ss

Example: "2023-09-15 14:30:00"

When filtering by dates, you can use:

• Format: 2023-09-15 14:30:00
• Date only: 2023-09-15