Skip to content

BackendAPI.md

Latest commit

 

History

History
1131 lines (951 loc) · 20 KB

BackendAPI.md

File metadata and controls

1131 lines (951 loc) · 20 KB

API

When authorization is enabled, all API handlers require an Authorization header containing a valid token.

Errors

In case of an error, the service returns an appropriate HTTP status code and a response similar to the following:

{
  "statusMessage": "error reason here"
}

Categories API requests

name must be unique.

Get all

curl http://127.0.0.1:8080/api/category/list

Response

{
  "categories": [
    {
      "id": 1,
      "name": "fun"
    },
    {
      "id": 2,
      "name": "work"
    }
  ]
}

Filter

curl -X POST http://127.0.0.1:8080/api/category/filter -H "Content-Type: application/json" -d '{"name": "or"}'

Response

{
  "categories": [
    {
      "id": 2,
      "name": "work"
    },
    {
      "id": 3,
      "name": "new category name"
    }
  ]
}

Get by id

curl http://127.0.0.1:8080/api/category/list/1

Response

{
  "id": 1,
  "name": "fun"
}

Create

name must not be empty.

curl -X POST http://127.0.0.1:8080/api/category/list -H "Content-Type: application/json" -d '{"name": "category name"}'

Response

{
  "id": 1,
  "name": "category name"
}

Update

name must not be empty.

curl -X PUT http://127.0.0.1:8080/api/category/list/1 -H "Content-Type: application/json" -d '{"name": "new category name"}'

Response

{
  "id": 1,
  "name": "new category name"
}

Delete

curl -X DELETE http://127.0.0.1:8080/api/category/list/1

Response: HTTP 200 with empty body

Proxies API requests

type must be one of

  • DIRECT
  • PROXY
  • SOCKS
  • SOCKS4
  • SOCKS5
  • HTTP
  • HTTPS

address must not be empty except for type == DIRECT

Get all

curl http://127.0.0.1:8080/api/proxy/list

Response

{
  "proxies": [
    {
      "id": 1,
      "type": "HTTP",
      "address": "127.0.0.1:8080",
      "description": "local proxy"
    },
    {
      "id": 2,
      "type": "SOCKS",
      "address": "10.10.0.10:8080",
      "description": "dante"
    }
  ]
}

Filter

curl -X POST http://127.0.0.1:8080/api/proxy/filter -H "Content-Type: application/json" -d '{"type": "HTT", "address": "127"}'

Response

{
  "proxies": [
    {
      "id": 1,
      "type": "HTTP",
      "address": "127.0.0.1:8080",
      "description": "local proxy"
    }
  ]
}

Get by id

curl http://127.0.0.1:8080/api/proxy/list/1

Response

{
  "id": 1,
  "type": "HTTP",
  "address": "127.0.0.1:8080",
  "description": "local proxy"
}

Create

If type != DIRECT address must not be empty.

If type == DIRECT address must be empty.

curl -X POST http://127.0.0.1:8080/api/proxy/list -H "Content-Type: application/json" -d '{"type": "HTTP", "address": "127.0.0.1:1080", "description": "Proxy description"}'

Response

{
  "id": 3,
  "type": "HTTP",
  "address": "127.0.0.1:1080",
  "description": "Proxy description"
}

Update

If type != DIRECT provided or existing address must not be empty.

If any of type, address or description fields are not provided in request, corresponding values remain unchanged.

curl -X PUT http://127.0.0.1:8080/api/proxy/list/1 -H "Content-Type: application/json" -d '{"type": "HTTP", "address": "127.0.0.1:80", "description": "updated description"}'

Response

{
  "id": 1,
  "type": "HTTP",
  "address": "127.0.0.1:80",
  "description": "updated description"
}

Delete

curl -X DELETE http://127.0.0.1:8080/api/proxy/list/1

Response: HTTP 200 with empty body

Conditions API requests

type must be one of

  • host_domain_only
  • host_domain_subdomain
  • host_subdomain_only
  • url_shexp_match
  • url_regexp_match

expression must not be empty.

Condition types

Domain

  • type = "host_domain_only"

Host equals to provided domain.

Domain and subdomains

  • type = "host_domain_subdomain"

Host equals to provided domain or is subdomain of provided domain.

Subdomains only

  • type = "host_subdomain_only"

Host is subdomain of provided domain.

URL shell expression

  • type = "url_shexp_match"

URL regular expression

  • type = "url_regexp_match"

Get all

curl http://127.0.0.1:8080/api/condition/list

Response

{
  "conditions": [
    {
      "id": 1,
      "type": "host_domain_subdomain",
      "expression": "google.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    },
    {
      "id": 2,
      "type": "host_domain_only",
      "expression": "memes.com",
      "category": {
        "id": 1,
        "name": "fun"
      }
    },
    {
      "id": 3,
      "type": "host_subdomain_only",
      "expression": "noexample.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    }
  ]
}

Get by id

curl http://127.0.0.1:8080/api/condition/1

Response

{
  "id": 1,
  "type": "host_domain_subdomain",
  "expression": "google.com",
  "category": {
    "id": 2,
    "name": "work"
  }
}

Create

curl -X POST http://127.0.0.1:8080/api/condition/list -H "Content-Type: application/json" -d '{"type": "host_domain_only", "expression": "example.com", "categoryId": 1}'

Response

{
  "id": 4,
  "type": "host_domain_only",
  "expression": "example.com",
  "category": {
    "id": 1,
    "name": "fun"
  }
}

Update

If any of type, expression or categoryId fields are not provided in request, corresponding values remain unchanged.

 curl -X PUT http://127.0.0.1:8080/api/condition/list/1 -H "Content-Type: application/json" -d '{"type": "host_domain_subdomain", "expression": "example.com", "categoryId": 1}'

Response

{
  "id": 1,
  "type": "host_domain_subdomain",
  "expression": "example.com",
  "category": {
    "id": 1,
    "name": "fun"
  }
}

Delete

curl -X DELETE http://127.0.0.1:8080/api/condition/list/1

Response: HTTP 200 with empty body

Proxy rules API requests

Get all

curl http://127.0.0.1:8080/api/proxyrule/list

Response

{
  "proxyRules": [
    {
      "id": 1,
      "proxy": {
        "id": 1,
        "type": "HTTP",
        "address": "127.0.0.1:80",
        "description": "updated description"
      },
      "enabled": true,
      "name": "proxy group 1",
      "conditions": [
        {
          "id": 1,
          "type": "host_domain_subdomain",
          "expression": "google.com",
          "category": {
            "id": 2,
            "name": "work"
          }
        }
      ]
    }
  ]
}

Get by id

curl http://127.0.0.1:8080/api/proxyrule/list/1

Response

{
  "id": 1,
  "proxy": {
    "id": 1,
    "type": "HTTP",
    "address": "127.0.0.1:80",
    "description": "updated description"
  },
  "enabled": true,
  "name": "proxy group 1",
  "conditions": [
    {
      "id": 1,
      "type": "host_domain_subdomain",
      "expression": "google.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    }
  ]
}

Create

curl -X POST http://127.0.0.1:8080/api/proxyrule/list -H "Content-Type: application/json" -d '{"proxyId": 1, "enabled": true, "name": "proxy group 1", "conditionIds": [1,2]}'

Response

{
  "id": 4,
  "proxy": {
    "id": 1,
    "type": "HTTP",
    "address": "127.0.0.1:80",
    "description": "updated description"
  },
  "enabled": true,
  "name": "proxy group 1",
  "conditions": [
    {
      "id": 1,
      "type": "host_domain_subdomain",
      "expression": "google.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    },
    {
      "id": 2,
      "type": "host_domain_only",
      "expression": "example.com",
      "category": {
        "id": 1,
        "name": "fun"
      }
    }
  ]
}

Update

If any of proxyId, enabled, name or conditionIds fields are not provided in request, corresponding values remain unchanged.

curl -X PUT http://127.0.0.1:8080/api/proxyrule/list/1 -H "Content-Type: application/json" -d '{"proxyId": 1, "enabled": true, "name": "proxy group updated", "conditionIds": [2]}'

Response

{
  "id": 1,
  "proxy": {
    "id": 1,
    "type": "HTTP",
    "address": "127.0.0.1:80",
    "description": "updated description"
  },
  "enabled": true,
  "name": "proxy group updated",
  "conditions": [
    {
      "id": 2,
      "type": "host_domain_only",
      "expression": "example.com",
      "category": {
        "id": 1,
        "name": "fun"
      }
    }
  ]
}

Delete

curl -X DELETE http://127.0.0.1:8080/api/proxyrule/list/1

Response: HTTP 200 with empty body

Get conditions linked to proxy rules

curl http://127.0.0.1:8080/api/proxyrule/list/1/conditions

Response

{
  "conditions": [
    {
      "id": 1,
      "type": "host_domain_subdomain",
      "expression": "google.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    },
    {
      "id": 2,
      "type": "host_domain_only",
      "expression": "example.com",
      "category": {
        "id": 1,
        "name": "fun"
      }
    }
  ]
}

Add condition to proxy rules

curl -X POST http://127.0.0.1:8080/api/proxyrule/list/1/conditions/3

Returns updated conditions for proxy rules object.

{
  "conditions": [
    {
      "id": 1,
      "type": "host_domain_subdomain",
      "expression": "google.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    },
    {
      "id": 2,
      "type": "host_domain_only",
      "expression": "example.com",
      "category": {
        "id": 1,
        "name": "fun"
      }
    },
    {
      "id": 3,
      "type": "host_domain_only",
      "expression": "noexample.com",
      "category": {
        "id": 2,
        "name": "work"
      }
    }
  ]
}

Delete condition from proxy rules

curl -X DELETE http://127.0.0.1:8080/api/proxyrule/list/1/conditions/3

Response: HTTP 200 with empty body

PAC API requests

Get all

curl http://127.0.0.1:8080/api/pac/list

Response

{
  "pacs": [
    {
      "id": 1,
      "name": "pac 1",
      "description": "some PAC",
      "serve": true,
      "servePath": "pac1.pac",
      "saveToFS": false,
      "saveToFSPath": "pac1.pac",
      "fallbackProxy": {
        "id": 4,
        "type": "DIRECT",
        "address": "",
        "description": "no proxy"
      }
    }
  ]
}

Get by id

curl http://127.0.0.1:8080/api/pac/list/1

Response

{
  "id": 1,
  "name": "pac 1",
  "description": "some PAC",
  "proxyRules": [
    {
      "proxyRule": {
        "id": 1,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "some proxy group",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 2,
            "type": "host_domain_subdomain",
            "expression": "memes.com",
            "category": {
              "id": 1,
              "name": "fun"
            }
          }
        ]
      },
      "priority": 1
    }
  ],
  "serve": true,
  "servePath": "pac1.pac",
  "saveToFS": false,
  "saveToFSPath": "pac1.pac",
  "fallbackProxy": {
    "id": 4,
    "type": "DIRECT",
    "address": "",
    "description": "no proxy"
  }
}

Create

curl -X POST http://127.0.0.1:8080/api/pac/list -H "Content-Type: application/json" -d '{"name": "pac 2", "description": "PAC for something else", "proxyRules": [{"proxyRuleId": 1, "priority":1}], "fallbackProxyId": 3, "serve": true, "servePath": "pac2.pac", "saveToFS": true, "saveToFSPath": "pac2.pac"}'

Response

{
  "id": 2,
  "name": "pac 2",
  "description": "PAC for something else",
  "proxyRules": [
    {
      "proxyRule": {
        "id": 1,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "some proxy group",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 2,
            "type": "host_domain_subdomain",
            "expression": "memes.com",
            "category": {
              "id": 1,
              "name": "fun"
            }
          }
        ]
      },
      "priority": 1
    }
  ],
  "serve": true,
  "servePath": "pac2.pac",
  "saveToFS": true,
  "saveToFSPath": "pac2.pac",
  "fallbackProxy": {
    "id": 3,
    "type": "PROXY",
    "address": "127.0.0.1:1080",
    "description": "Proxy description"
  }
}

Update

curl -X PUT http://127.0.0.1:8080/api/pac/list/2 -H "Content-Type: application/json" -d '{"name": "pac 2 updated", "description": "PAC for something else updated", "proxyRules": [{"proxyRuleId": 2, "priority":1}], "fallbackProxyId": 2, "serve": false, "servePath": "pac2updated.pac", "saveToFS": false, "saveToFSPath": "pac2updated.pac"}'

Response

{
  "id": 2,
  "name": "pac 2 updated",
  "description": "PAC for something else updated",
  "proxyRules": [
    {
      "proxyRule": {
        "id": 2,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "proxy group 1",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 3,
            "type": "host_subdomain_only",
            "expression": "ya.ru",
            "category": {
              "id": 2,
              "name": "work"
            }
          }
        ]
      },
      "priority": 1
    }
  ],
  "serve": false,
  "servePath": "pac2updated.pac",
  "saveToFS": false,
  "saveToFSPath": "pac2updated.pac",
  "fallbackProxy": {
    "id": 2,
    "type": "SOCKS",
    "address": "10.10.0.10:8080",
    "description": "dante"
  }
}

Delete

curl -X DELETE http://127.0.0.1:8080/api/pac/list/2

Response: HTTP 200 with empty body

Get proxy rules linked to PAC

curl http://127.0.0.1:8080/api/pac/list/1/proxyrules

Response

{
  "proxyRules": [
    {
      "proxyRule": {
        "id": 1,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "some proxy group",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 2,
            "type": "host_domain_subdomain",
            "expression": "memes.com",
            "category": {
              "id": 1,
              "name": "fun"
            }
          }
        ]
      },
      "priority": 1
    }
  ]
}

Add proxy rules to PAC

curl -X POST http://127.0.0.1:8080/api/pac/list/1/proxyrules/2?priority=2

Returns updated proxy rules for PAC object.

{
  "proxyRules": [
    {
      "proxyRule": {
        "id": 1,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "some proxy group",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 2,
            "type": "host_domain_subdomain",
            "expression": "memes.com",
            "category": {
              "id": 1,
              "name": "fun"
            }
          }
        ]
      },
      "priority": 1
    },
    {
      "proxyRule": {
        "id": 2,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "proxy group 1",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 3,
            "type": "host_subdomain_only",
            "expression": "ya.ru",
            "category": {
              "id": 2,
              "name": "work"
            }
          }
        ]
      },
      "priority": 2
    }
  ]
}

Set proxy rule priority in PAC

curl -X PATCH http://127.0.0.1:8080/api/pac/list/1/proxyrules/2?priority=10

Returns updated proxy rules for PAC object.

{
  "proxyRules": [
    {
      "proxyRule": {
        "id": 1,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "some proxy group",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 2,
            "type": "host_domain_subdomain",
            "expression": "memes.com",
            "category": {
              "id": 1,
              "name": "fun"
            }
          }
        ]
      },
      "priority": 1
    },
    {
      "proxyRule": {
        "id": 2,
        "proxy": {
          "id": 1,
          "type": "HTTP",
          "address": "127.0.0.1:8080",
          "description": "local proxy"
        },
        "enabled": true,
        "name": "proxy group 1",
        "conditions": [
          {
            "id": 1,
            "type": "host_domain_only",
            "expression": "google.com",
            "category": {
              "id": 2,
              "name": "work"
            }
          },
          {
            "id": 3,
            "type": "host_subdomain_only",
            "expression": "ya.ru",
            "category": {
              "id": 2,
              "name": "work"
            }
          }
        ]
      },
      "priority": 10
    }
  ]
}

Delete proxy rules from PAC

curl -X DELETE http://127.0.0.1:8080/api/pac/list/1/proxyrules/2

Response: HTTP 200 with empty body

User API requests

Login

Password is SHA256 of password string.

Here 8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918 = SHA256("admin").

curl -X POST http://127.0.0.1:8080/api/user/login?user=admin\&password=8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918

Response

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiY3JlYXRlZEF0IjoxNzY1MjIzODgzfQ.chtn-6SX3Q_tj2NbmGLkEwJB6NUcXDRms5q59QEn-Yx0L7yoQUzynHpOhCD8t2BU6V0xpkI-3Sp_IKYpj44rLA"
}

Logout

curl -X POST http://127.0.0.1:8080/api/user/logout -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiY3JlYXRlZEF0IjoxNzY1MjIzNjU2fQ.3z8VeN0FerbZT4w8U8aCjkK7O9NouKMFScEwXly22FxIbTkkpADS-1yWZmTivIgqxA_G5ffH4-L8A2n-275ELg'

Response: HTTP 200 with empty body

Get profile

curl http://127.0.0.1:8080/api/user/profile -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiY3JlYXRlZEF0IjoxNzY1MjIzNjU2fQ.3z8VeN0FerbZT4w8U8aCjkK7O9NouKMFScEwXly22FxIbTkkpADS-1yWZmTivIgqxA_G5ffH4-L8A2n-275ELg'

Response

{
  "userName": "admin"
}