API Guide - Service

  • Updated on Apr 27, 2022

List services

Fetches a list of services in your Banyan organization.

Review the Service Spec Syntax for more information on the Service data structures.

HTTP Request

GET /v1/registered_services

URL Parameters

N/A

Query Parameters

Parameter Format Description
ServiceID String The ID of the Service to retrieve
DefaultServices String(“True”/”False”) Default services flag.
FriendlyName String Friendly Name of the Service.

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Status Codes and Errors

Value Description
200 OK

Response Headers

N/A

HTTP Response Body

[
  {
    "ServiceID": "example-test-service.testservice-shield.bnn",
    "ServiceName": "example-test-service",
    "FriendlyName": "example-friendly-name",
    "ClusterName": "testservice-shield",
    "ServiceType": "origin",
    "ServiceDiscovery": "",
    "ServiceVersion": 7,
    "Description": "example-test-service",
    "CreatedBy": "mahesh.dere@joshsoftware.com",
    "CreatedAt": 1623766242398427395,
    "LastUpdatedBy": "mahesh.dere@joshsoftware.com",
    "LastUpdatedAt": 1625566003335517158,
    "DeletedBy": "",
    "DeletedAt": 0,
    "External": "",
    "OIDCEnabled": "TRUE",
    "OIDCClientSpec": "{\"trust_auth\":\"https://testservice.trust-dev03.bnntest.com/v2/auth\",\"trust_cb\":\"https://example-test-service.bnntest.com/bnn_trust_cb\",\"client_id\":\"[REDACTED]\",\"client_secret\":\"[REDACTED]\",\"trust_callbacks\":{\"example-test-service.bnntest.com:443\":\"https://example-test-service.bnntest.com/bnn_trust_cb\"},\"disallow_async_auth_redirect\":false}",
    "ServiceSpec": "{\"kind\":\"BanyanService\",\"apiVersion\":\"rbac.banyanops.com/v1\",\"type\":\"origin\",\"metadata\":{\"tags\":{\"template\":\"WEB_USER\",\"service_app_type\":\"WEB\",\"protocol\":\"https\",\"user_facing\":\"true\",\"icon\":\"\",\"description_link\":\"https://example-test-service.bnntest.com\",\"domain\":\"example-test-service.bnntest.com\",\"port\":\"443\"},\"name\":\"example-test-service\",\"description\":\"example-test-service\",\"cluster\":\"testservice-shield\"},\"spec\":{\"attributes\":{\"frontend_addresses\":[{\"cidr\":\"\",\"port\":\"443\"}],\"host_tag_selector\":[{\"com.banyanops.hosttag.site_name\":\"testservice-jenkins.bnntest.com\"}],\"tls_sni\":[\"example-test-service.bnntest.com\"]},\"backend\":{\"target\":{\"name\":\"10.128.0.54\",\"port\":\"8080\",\"tls\":false,\"tls_insecure\":false,\"client_certificate\":false},\"dns_overrides\":{},\"whitelist\":[],\"http_connect\":false,\"allow_patterns\":[]},\"cert_settings\":{\"dns_names\":[\"example-test-service.bnntest.com\"],\"custom_tls_cert\":{\"enabled\":false,\"cert_file\":\"\",\"key_file\":\"\"},\"letsencrypt\":false},\"http_settings\":{\"enabled\":true,\"oidc_settings\":{\"enabled\":true,\"service_domain_name\":\"https://example-test-service.bnntest.com\",\"post_auth_redirect_path\":\"\",\"api_path\":\"\"},\"http_health_check\":{\"enabled\":false,\"method\":\"\",\"path\":\"\",\"user_agent\":\"\",\"from_address\":[],\"https\":false},\"exempted_paths\":{\"enabled\":false,\"paths\":[],\"patterns\":[]},\"headers\":{}},\"client_cidrs\":[]}}",
    "UserFacing": "TRUE",
    "Protocol": "https",
    "Domain": "example-test-service.bnntest.com",
    "Port": 443,
    "Enabled": "TRUE",
    "IsDefault": false
  },
  {
    "ServiceID": "example-test-servicetest.testservice-shield.bnn",
    "ServiceName": "example-test-servicetest",
    "FriendlyName": "example-friendly-name",
    "ClusterName": "testservice-shield",
    "ServiceType": "origin",
    "ServiceDiscovery": "",
    "ServiceVersion": 7,
    "Description": "example-test-servicetest",
    "CreatedBy": "mahesh.dere@joshsoftware.com",
    "CreatedAt": 1623766242398427395,
    "LastUpdatedBy": "mahesh.dere@joshsoftware.com",
    "LastUpdatedAt": 1625566003335517158,
    "DeletedBy": "",
    "DeletedAt": 0,
    "External": "",
    "OIDCEnabled": "TRUE",
    "OIDCClientSpec": "{\"trust_auth\":\"https://testservice.trust-dev03.bnntest.com/v2/auth\",\"trust_cb\":\"https://example-test-servicetest.bnntest.com/bnn_trust_cb\",\"client_id\":\"[REDACTED]\",\"client_secret\":\"[REDACTED]\",\"trust_callbacks\":{\"example-test-servicetest.bnntest.com:443\":\"https://example-test-servicetest.bnntest.com/bnn_trust_cb\"},\"disallow_async_auth_redirect\":false}",
    "ServiceSpec": "{\"kind\":\"BanyanService\",\"apiVersion\":\"rbac.banyanops.com/v1\",\"type\":\"origin\",\"metadata\":{\"tags\":{\"template\":\"WEB_USER\",\"service_app_type\":\"WEB\",\"protocol\":\"https\",\"user_facing\":\"true\",\"icon\":\"\",\"description_link\":\"https://example-test-servicetest.bnntest.com\",\"domain\":\"example-test-servicetest.bnntest.com\",\"port\":\"443\"},\"name\":\"example-test-servicetest\",\"description\":\"example-test-servicetest\",\"cluster\":\"testservice-shield\"},\"spec\":{\"attributes\":{\"frontend_addresses\":[{\"cidr\":\"\",\"port\":\"443\"}],\"host_tag_selector\":[{\"com.banyanops.hosttag.site_name\":\"testservice-jenkins.bnntest.com\"}],\"tls_sni\":[\"example-test-servicetest.bnntest.com\"]},\"backend\":{\"target\":{\"name\":\"10.128.0.54\",\"port\":\"8080\",\"tls\":false,\"tls_insecure\":false,\"client_certificate\":false},\"dns_overrides\":{},\"whitelist\":[],\"http_connect\":false,\"allow_patterns\":[]},\"cert_settings\":{\"dns_names\":[\"example-test-servicetest.bnntest.com\"],\"custom_tls_cert\":{\"enabled\":false,\"cert_file\":\"\",\"key_file\":\"\"},\"letsencrypt\":false},\"http_settings\":{\"enabled\":true,\"oidc_settings\":{\"enabled\":true,\"service_domain_name\":\"https://example-test-servicetest.bnntest.com\",\"post_auth_redirect_path\":\"\",\"api_path\":\"\"},\"http_health_check\":{\"enabled\":false,\"method\":\"\",\"path\":\"\",\"user_agent\":\"\",\"from_address\":[],\"https\":false},\"exempted_paths\":{\"enabled\":false,\"paths\":[],\"patterns\":[]},\"headers\":{}},\"client_cidrs\":[]}}",
    "UserFacing": "TRUE",
    "Protocol": "https",
    "Domain": "example-test-servicetest.bnntest.com",
    "Port": 443,
    "Enabled": "TRUE",
    "IsDefault": false
  }
]

Create a new service or update an existing service

HTTP Request

POST /v1/insert_registered_service

URL Parameters

N/A

Query Parameters

N/A

Request Headers

Authorization: Bearer $AUTHTOKEN, ContentType: application/json

Request Body

JSON string with the Service Spec

Sample JSON body:

{
  "kind": "BanyanService",
  "apiVersion": "rbac.banyanops.com/v1",
  "type": "origin",
  "metadata": {
    "name": "example_web_service",
    "friendly_name": "example_friendly_name",
    "description": "web service example ",
    "cluster": "release-rc",
    "tags": {
      "template": "WEB_USER",
      "user_facing": "true",
      "protocol": "https",
      "domain": "example.bnntest.com",
      "port": "443",
      "icon": "cloud",
      "service_app_type": "WEB"
    }
  },
  "spec": {
    "attributes": {
      "frontend_addresses": [
        {
          "cidr": "",
          "port": "443"
        }
      ],
      "host_tag_selector": [
        {
          "com.banyanops.hosttag.site_name": "deva-net-mar4"
        }
      ],
      "tls_sni": [
        "example.bnntest.com"
      ]
    },
    "backend": {
      "target": {
        "name": "34.70.156.134",
        "port": "433",
        "tls": true,
        "tls_insecure": true,
        "client_certificate": false
      },
      "dns_overrides": {
      },
      "whitelist": [  
      ],
      "http_connect": false,
      "allow_patterns": [
      ]
    },
    "cert_settings": {
      "letsencrypt": true,
      "dns_names": [
        "example.bnntest.com"
      ],
      "custom_tls_cert": {
        "enabled": false,
        "cert_file": "",
        "key_file": ""
      }
    },
    "http_settings": {
      "enabled": true,
      "oidc_settings": {
        "enabled": true,
        "service_domain_name": "https://example.bnntest.com",
        "post_auth_redirect_path": "",
        "api_path": ""
      },
      "http_health_check": {
        "enabled": false,
        "method": "",
        "path": "",
        "user_agent": "",
        "from_address": [
        ],
        "https": false
      },
      "exempted_paths": {
        "enabled": false,
        "paths": [
        ],
        "patterns": [
          {
            "hosts": [
              {
                "origin_header": [   
                ],
                "target": [
                ]
              }
            ],
            "methods": [ 
            ],
            "mandatory_headers": [ 
            ],
            "paths": [
            ],
            "source_cidrs": [
            ]
          }
        ]
      }
    },
    "client_cidrs": [
    ]
  }
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

Response Body

If a Service with the name does exist in the cluster, then it is updated.

If a Service with the name doesn’t already exist in the cluster, then a new Service is created and the complete service is returned.

{
  "ServiceID": "example-test-service.testservice-shield.bnn",
  "ServiceName": "example-test-service",
  "FriendlyName":"example-friendly-name",
  "ClusterName": "testservice-shield",
  "ServiceType": "origin",
  "ServiceDiscovery": "",
  "ServiceVersion": 7,
  "Description": "example-test-service",
  "CreatedBy": "mahesh.dere@joshsoftware.com",
  "CreatedAt": 1623766242398427395,
  "LastUpdatedBy": "mahesh.dere@joshsoftware.com",
  "LastUpdatedAt": 1625566003335517158,
  "DeletedBy": "",
  "DeletedAt": 0,
  "External": "",
  "OIDCEnabled": "TRUE",
  "OIDCClientSpec": "{\"trust_auth\":\"https://testservice.trust-dev03.bnntest.com/v2/auth\",\"trust_cb\":\"https://example-test-service.bnntest.com/bnn_trust_cb\",\"client_id\":\"[REDACTED]\",\"client_secret\":\"[REDACTED]\",\"trust_callbacks\":{\"example-test-service.bnntest.com:443\":\"https://example-test-service.bnntest.com/bnn_trust_cb\"},\"disallow_async_auth_redirect\":false}",
  "ServiceSpec": "{\"kind\":\"BanyanService\",\"apiVersion\":\"rbac.banyanops.com/v1\",\"type\":\"origin\",\"metadata\":{\"tags\":{\"template\":\"WEB_USER\",\"service_app_type\":\"WEB\",\"protocol\":\"https\",\"user_facing\":\"true\",\"icon\":\"\",\"description_link\":\"https://example-test-service.bnntest.com\",\"domain\":\"example-test-service.bnntest.com\",\"port\":\"443\"},\"name\":\"example-test-service\",\"description\":\"example-test-service\",\"cluster\":\"testservice-shield\"},\"spec\":{\"attributes\":{\"frontend_addresses\":[{\"cidr\":\"\",\"port\":\"443\"}],\"host_tag_selector\":[{\"com.banyanops.hosttag.site_name\":\"testservice-jenkins.bnntest.com\"}],\"tls_sni\":[\"example-test-service.bnntest.com\"]},\"backend\":{\"target\":{\"name\":\"10.128.0.54\",\"port\":\"8080\",\"tls\":false,\"tls_insecure\":false,\"client_certificate\":false},\"dns_overrides\":{},\"whitelist\":[],\"http_connect\":false,\"allow_patterns\":[]},\"cert_settings\":{\"dns_names\":[\"example-test-service.bnntest.com\"],\"custom_tls_cert\":{\"enabled\":false,\"cert_file\":\"\",\"key_file\":\"\"},\"letsencrypt\":false},\"http_settings\":{\"enabled\":true,\"oidc_settings\":{\"enabled\":true,\"service_domain_name\":\"https://example-test-service.bnntest.com\",\"post_auth_redirect_path\":\"\",\"api_path\":\"\"},\"http_health_check\":{\"enabled\":false,\"method\":\"\",\"path\":\"\",\"user_agent\":\"\",\"from_address\":[],\"https\":false},\"exempted_paths\":{\"enabled\":false,\"paths\":[],\"patterns\":[]},\"headers\":{}},\"client_cidrs\":[]}}",
  "UserFacing": "TRUE",
  "Protocol": "https",
  "Domain": "example-test-service.bnntest.com",
  "Port": 443,
  "Enabled": "TRUE",
  "IsDefault": false
}

Delete a service

HTTP Request

DELETE /v1/delete_registered_service

URL Parameters

N/A

Query Parameters

Parameter Format Description
ServiceID String The ID of the Service to delete

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Status Codes and Errors

Value Description
200 OK

Response Headers

N/A

HTTP Response Body

N/A


Enable a registered service

Enables a registered service and then sends the notification to all Shields of its Organization.

HTTP Request

POST /v1/enable_registered_service?ServiceID=S

URL Parameters

NA

Query Parameters

Parameter Format Description
ServiceID String The ID of the service which needs to be enabled.

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

NA

Status Codes and Errors

Value Description
200 OK
400 Bad request
401 Unauthorized
500 Internal Server Error

Response Headers

N/A

Response Body

{
    "Message": "Service sample-service.cluster.bnn enabled successfully"
}

Disable a registered service

This endpoint disables a registered service and then sends the notification to all Shields of its Organization.

HTTP Request

POST /v1/disable_registered_service?ServiceID=S

URL Parameters

NA

Query Parameters

Parameter Format Description
ServiceID String The ID of the service which needs to be disabled

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

NA

Status Codes and Errors

Value Description
200 OK
400 Bad request
401 Unauthorized
500 Internal Server Error

Response Headers

N/A

Response Body

{
    "Message": "Service sample-service.cluster.bnn disabled successfully"
}

Create a service bundle

Creates a new service bundle or add one service to a bundle.

HTTP Requests

POST /v2/bundle - create a service bundle.

POST /v2/bundle/<bundle_id>/service - add one service to a bundle.

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

Sample JSON body/bundle:

{
    "bundle_name": "some bundle",
    "description": "some description",
    "service_ids": ["2", "3"],
    "bulk_connect": true
}

Sample JSON body /bundle/ /service - add one service to a bundle

{
    "service_id": "1"
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {
        "id": "d9ae7a0d-9d67-4d8f-b308-65cd09931e00",
        "bundle_name": "bundle 1",
        "description": "description",
        "is_admin_created": true,
        "bulk_connect": false,
        "service_ids": [
            "1"
        ],
        "created_at": 1630679201606586242,
        "updated_at": 1630679201606586242,
        "created_by_user_id": "f7bc1371-e6e7-46c1-a00a-61f1eb9b9d11"
    }
}

Update an existing service bundle

Updates an existing service bundle.

HTTP Request

PUT /v2/bundle/<bundle_id>

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body:

{
    "bundle_name": "new bundle name",
    "description": "new description",
    "service_ids": ["1", "2", "3"],
    "bulk_connect": false
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {
        "id": "1938626b-3803-4b6c-b156-8904a420edaf",
        "bundle_name": "new bundle name",
        "description": "new description",
        "is_admin_created": true,
        "bulk_connect": false,
        "service_ids": [
            "1","2","3"
        ],
        "created_at": 1630679346534874803,
        "updated_at": 1630679384782177024,
        "created_by_user_id": "f7bc1371-e6e7-46c1-a00a-61f1eb9b9d11"
    }
}

Delete a service bundle

Delete an existing service bundle or delete one service from a bundle.

HTTP Request

DELETE /v2/bundle/<bundle_id> - delete a service bundle

DELETE /v2/bundle/<bundle_id>/service - remove one service from a bundle

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body /bundle:

{}

Sample JSON body /bundle/ /service - remove one service from a bundle

{
    "service_id": "1"
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {}
}

Error Response Body

Possible error response messages | Error Code | Error Message | Description | ————————- | ————————————- | —— | TOKEN_INVALID | unauthorized access | when the authentication token provided is invalid | INTERNAL_SERVER_ERROR | Internal server error has occurred while processing the request | when the internal server error | NOT_FOUND | Requested resource not found | when the bundle does not exist | UNAUTHORIZED_ACCESS | unauthorized access | when the enduser is unauthorized to delete this bundle

Example of error response body json

Returns error the internal server error

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Internal server error has occurred while processing the request"
  },
  "request_id": "0441b480-1459-4e61-a757-184b107a2f93",
  "Message": "Internal server error has occurred while processing the request"
}

Add a service to a bundle

Associate a new service with a bundle.

HTTP Request

POST /v2/service_bundle

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body:

{
    "bundle_id": "my-bundle-id",
    "service_ids": ["1", "2", "3"]
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {
        "bundled_services": [
            {
                "id": "bundled-service-id1",
                "org_id": "org-id",
                "bundle_id": "my-bundle-id",
                "service_id": "1",
                "created_at": 123456,
                "updated_at": 123456
            },
            {
                "id": "bundled-service-id2",
                "org_id": "org-id",
                "bundle_id": "my-bundle-id",
                "service_id": "2",
                "created_at": 123456,
                "updated_at": 123456
            },
            {
                "id": "bundled-service-id3",
                "org_id": "org-id",
                "bundle_id": "my-bundle-id",
                "service_id": "3",
                "created_at": 123456,
                "updated_at": 123456
            }
        ]
    }
}

Remove a service from a bundle

Removes an existing association between a service and a bundle.

HTTP Request

DELETE /v2/service_bundle/<bundled-service-id>

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body:

{}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {}
}