API Guide - Service
- Updated on Apr 27, 2022
- List services
- Create a new service or update an existing service
- Delete a service
- Enable a registered service
- Disable a registered service
- Create a service bundle
- Update an existing service bundle
- Delete a service bundle
- Add a service to a bundle
- Remove a service from a bundle
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_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_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": {}
}